Introducing Microsoft BizTalk Server 2002

Integrating your company's internal applications has traditionally been difficult. Integrating them with external customers and suppliers has been even harder. But with Microsoft® BizTalk™ Server 2002, you can address all of your integration challenges from the enterprise to the Internet. The following illustration gives one example of orchestrating your business from internal applications to cross-company business processes.

BizTalk Server 2002 helps you orchestrate your business, from internal applications to cross-company business processes.

A member of the Microsoft® .NET Enterprise Server family of products, BizTalk Server 2002 unites enterprise application integration (EAI) and business-to-business (B2B) integration. Whether your company is an e-commerce supplier, distributor, or aggregator, BizTalk Server helps you orchestrate your business—all of it—from internal applications to cross-company business processes.

BizTalk Server helps you to integrate

Your interest in BizTalk Server indicates that you are involved in integration at some level. Maybe you are responsible for integrating your company's fulfillment system with other internal applications. Perhaps you have been mandated with integrating your newer Web-facing commerce systems with your back-end manufacturing and distribution systems. Or maybe your task is devising a way to use the Internet to integrate your business processes with those of key suppliers and distributors.

With strong support for XML, HTTP, HTTPS, SMTP, SSL, S/MIME, and x509v3 certificates, BizTalk Server is a powerful example of applying Internet-standard technologies to solve your integration issues.

About this Introduction

This Introduction provides a high-level view of BizTalk Server 2002. It contains illustrations, links, and definitions to help you better understand how you can use BizTalk Server to solve the unique e-commerce issues that face your company or organization.

The following topics are covered in this section:

  • Getting Started

  • Using BizTalk Server 2002 Help

Copyright © 1999–2001 Microsoft Corporation.
All rights reserved.


Getting Started

Microsoft® BizTalk™ Server 2002 provides a powerful development and execution environment that integrates loosely coupled, long-running business processes from the enterprise to the Internet. BizTalk Server can handle transactions that run as long as weeks or months, not just minutes or hours.

BizTalk Server 2002 features include the ability to design and execute state-full business processes in the form of XLANG schedules, integrate existing applications, define document specifications and specification transformations, and monitor and log run-time activity.

BizTalk Server provides a standard gateway for sending and receiving documents across the Internet, as well as providing a range of services that ensure data integrity, delivery, security, and support for the BizTalk Framework and other key document formats, such as Extensible Markup Language (XML), electronic data interchange (EDI), and flat files.

For information about BizTalk Framework 2.0, as well as information about BizTalk Server product resources such as community services, a large library of schemas, and white papers, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk).

Why use BizTalk Server?

Because it makes hard problems easier to solve. BizTalk Server integrates two key features—orchestration and messaging—into a single product. While a powerful messaging engine handles message transport and mapping, BizTalk Orchestration Services can orchestrate business processes composed of components, and messages that are sent and received using the BizTalk Messaging Service.

For example, BizTalk Server enables you to:

  • Build dynamic business processes. The BizTalk Server infrastructure helps you to quickly integrate, manage, and automate dynamic business processes by exchanging business documents among applications, within or across organizational boundaries. With all the tools you need for business process orchestration, BizTalk Server helps you build processes that span applications and businesses over the Internet.

  • Integrate applications and business partners. BizTalk Server makes it easy for developers to integrate applications and businesses together. Business analysts and application developers benefit from graphical tools for building schema for business documents, performing schema transformation, establishing trading partner relationships, and tracking and analyzing data. With support for XML and standard Internet technologies, BizTalk Server extends the features of traditional e-commerce and EDI to entire e-commerce communities.

  • Ensure interoperability using public standards. With extensive support for public standards and specifications, such as XML, EDI, Hypertext Transfer Protocol (HTTP and HTTPS), and security standards, such as public key encryption and digital signatures, BizTalk Server ensures the highest level of interoperability and security with your applications and business partners.

BizTalk Server uses XML internally to define the data and structure of your business documents, and it uses standard Internet protocols like HTTP and Simple Mail Transfer Protocol (SMTP) to deliver these documents to their destinations, enabling you to interoperate with various applications running in any environment as long as those applications support Internet standards. You can send documents to BizTalk Server as XML, EDI, or flat files.

What specific problems does BizTalk Server solve?

Problems associated with internal and external integration.

Historically, businesses have purchased enterprise applications from different vendors over several years, resulting in a variety of applications running on several platforms. Because each application was designed to fulfill a specific task, such as warehousing or customer relationship management (CRM), integration with other applications was not common. As a result, a company that decided to integrate its internal applications found it an expensive and time-consuming task.

Consider these common integration complaints:

  • Disparate applications: "It's too difficult to integrate dissimilar applications within my company."

  • Programming overruns: "It takes too long to develop integrated solutions for my company's enterprise resource plan."

  • Dissimilar reports: "There is no way to generate integrated, timely reports from my various applications because the data is stored in so many places."

  • Modification difficulties: "Once my internal applications are integrated, changing them is arduous and expensive."

  • No set procedure: "My company does not have a consistent method for implementing our critical business processes."

  • Partnering headaches: "It's too difficult to integrate my company's business processes with my trading partner's."

  • Changing partners: "If another business offers me a better deal, it's too difficult to take advantage of this with all the IT infrastructure that is required."

Today, the popularity of the World Wide Web has brought with it the prospect of e-commerce—doing business over the Internet. However, while integrating in-house applications is difficult, trading with customers and suppliers through the Internet is far more complicated, primarily because of increased security and reliability issues associated with online transactions. BizTalk Server is designed to help you solve these problems. Using graphical tools like BizTalk Orchestration Designer and BizTalk Editor, BizTalk Server lets you design your unique business processes in a visual design environment. BizTalk Server then executes the visual diagram, providing rapid application development (RAD) for business processes.

Tutorials

You can get immediate hands-on experience with BizTalk Server 2002 by going through the tutorials provided in this manual:

  • Learning BizTalk Server 2002 helps you better understand how to use BizTalk Editor, BizTalk Mapper, BizTalk Messaging Manager, BizTalk Administrator, and BizTalk Orchestration Designer to configure BizTalk Server to run a business-to-business automated procurement process.

  • The BizTalk Server 2002 Tutorial explains step-by-step how to configure BizTalk Server processes.

  • The E-Procurement Sample is an end-to-end sample that uses BizTalk Server, the Internet, and correlation to demonstrate how to automate the procurement process that takes place between your company and its suppliers.

Samples

BizTalk Server 2002 includes more than 20 samples that illustrate much of the BizTalk Server functionality. Samples provided in the BizTalk Server Software Development Kit (SDK) are located in the folder \Program Files\Microsoft BizTalk Server\SDK on the installation drive.

BizTalk Server samples are organized into two categories:

  • BizTalk Messaging Services Code Samples

  • BizTalk Orchestration Services Code Samples

In this section

The following topics are covered in this section:

  • What's New in BizTalk Server 2002

  • Who Is BizTalk Server For?

  • How Does BizTalk Server Work?

  • BizTalk Server Features

  • BizTalk Server Application Model

  • BizTalk Server Administration Model

Copyright © 1999–2001 Microsoft Corporation.
All rights reserved.

Did you find this information useful? Please send your suggestions and comments about the documentation to BizTalk Server Documentation Feedback@microsoft.com


What's New in BizTalk Server 2002

Microsoft® BizTalk™ Server 2002 Enterprise Edition includes the following enhancements:

  • Intra-company deployment of BizTalk Server objects. BizTalk Server 2002 enhances intra-company deployment by providing a BizTalk Server replication driver for use with Microsoft Application Center 2000. Application Center 2000 eases deployment by automatically migrating and synchronizing your BizTalk Server objects across disparate environments. Application Center 2000 enables two key deployment scenarios:
    • From development, through staging, to production

    • Across a production server farm
  • Rapid inter-company deployment and testing of public document interfaces to partners. With the introduction of SEED packages, BizTalk Server 2002 provides streamlined inter-company deployment capability. SEED packages contain the document schemas and other related information that a company (initiator) sends to and receives from its trading partners (recipient). SEED packages are created one time, then deployed to many trading partners. The SEED package is opened by a trading partner, who enters the organization's unique configuration requirements. The configuration information is automatically created, tested locally in the trading partner's environment, and then tested against a remote server. Once a configuration is tested, the partners can move the configuration into production. The BizTalk SEED Wizard decreases the trading partner's setup time, and decreases the SEED package initiator's testing time.

  • Detailed monitoring and event management. BizTalk Server 2002 includes new and enhanced Windows Management Instrumentation (WMI) events that enable you to manage business processes. To take advantage of this enhanced event management, BizTalk Server 2002 ships with a management pack—specific to BizTalk Server—for Microsoft Operations Manager (MOM). Using the BizTalk Server 2002 Enterprise Edition Management Pack, you can rapidly select from a set of predefined alerts and rules to tailor your applications so you can get the precise information you need from either a single event or combined events. Using MOM and the new BizTalk Custom Counters WMI class, you can also build customized monitoring applications to learn more detail about the inner workings of your BizTalk Server installation.

  • Increased XML Web services support. As applications are being created from many disparate systems, including Web services, the need to manage them into a business process increases. BizTalk Server 2002 ships with the SOAP Toolkit 2.0 Service Pack 2 (SP2), which enables you to orchestrate business processes that include XML Web services. The SOAP Toolkit 2.0 SP2 is located in the WebServices directory on the Microsoft BizTalk Server 2002 installation CD.

  • Remote administration. The BizTalk Server Administration console is now part of the Tools-only installation. The administration console can be installed on a remote computer that is not running BizTalk Server and can be pointed to any remote BizTalk Server in your environment for easier, more flexible, administration capability.

  • HTTP receive function. BizTalk Server now includes a high-performance ISAPI HTTP receive function that is managed and configured directly inside the BizTalk Server Administration console.

  • Separate transaction handling and exception handling inside BizTalk Orchestration Designer. The BizTalk Orchestration Designer now provides an option to specify that a transaction is being used for exception handling. This increases performance by minimizing database read/write activity.

  • Integrated SQL security. BizTalk Server 2002 uses integrated Microsoft Windows® security to access Microsoft SQL Server™. This means that BizTalk Server, rather than using SQL credentials, uses the credentials of a Windows 2000 user to determine SQL privileges.

  • Database management. Several new utilities and scripts are provided to help you manage your Tracking database and XLANG persistence database.

  • XLANG correlation. When a business process is started, multiple schedule instances can now use a single message queue, and incoming messages on that queue can be correlated to a specific instance to continue the business process. In addition, the process of correlation to a running business process has been simplified.

  • XLANG schedule pooling. You can now specify a "pool of schedules," which is the maximum number of schedule instances that are allowed in memory at a time. This provides you with a fine level of control over computer resources and is particularly useful in cases where you are constrained by hardware. BizTalk Server 2002 takes advantage of COM+ object pooling for maximum performance.

  • Improved BizTalk Mapper. BizTalk Mapper has been upgraded to include the following features:
    • Mixed XML content is now supported.

    • You can now perform instance testing of native document instances (including XML and non-XML) directly in BizTalk Mapper.

    • The grid zone has been scaled to allow multiple pages.

    • Drag-and-drop capabilities have been added.

    • You can now write functoid scripts using Microsoft JScript®. Also, custom functoid assemblies can be written using Microsoft Visual C#™ .NET and Microsoft Visual Studio® .NET.
  • Improved BizTalk Editor. BizTalk Editor has been upgraded with the following features:
    • You can now create a native document instance.

    • Mixed XML content is now supported.

    • Drag-and-drop capabilities have been added.

    • You can now validate a document instance against a specification.

    • Record data typing is now supported.

    • You can now export XSD schemas directly from BizTalk Editor.

  • Enhanced documentation. More than 500 new pages of information have been added to BizTalk Server Help, including:
    • A new Getting Started section which includes topics such as Who Is BizTalk Server For?, How Does BizTalk Server Work?, and Building a BizTalk Server Solution.

    • Learning BizTalk Server 2002, seven lessons that explain the fundamental concepts surrounding BizTalk Server, and provide information that will help you understand the tools and processes that are required to start building solutions with BizTalk Server.

    • E-Procurement Sample, which uses BizTalk Server 2002, the Internet, and correlation to show how to automate the procurement process that takes place between your company and its suppliers.

    • An expanded BizTalk Server Developer's Toolbox, which provides all the information necessary for programmers of the C++ and Microsoft Visual Basic® programming languages to use or extend BizTalk Server 2002.
  • More samples. BizTalk Server 2002 includes more than 20 new samples that illustrate much of the new program functionality, including samples that show how to:
    • Refresh all BizTalk Messaging objects stored in WebDAV. See Refresh Messaging Manager.

    • Trace and log XLANG schedules for debugging. See XLANG Trace.

    • Submit documents greater than 4 megabytes (MB) to BizTalk Orchestration Services. See Message Queuing 4 MB Limit.

    • Submit multi-part Multipurpose Internet Mail Extensions (MIME) attachments to BizTalk Messaging Services. See Multi-Part MIME Attachment.

    • Submit multiple documents to XLANG schedules synchronously and query asynchronously. See XLANG Submit Synchronously and Query Asynchronously.

    • Submit self-routing documents. See Self-Routing.

    • Monitor the Suspended queue. See Suspended Queue Monitoring.

    • Use reliable messaging. See Reliable Messaging.

    • Use XLANG schedule pooling. See XLANG Schedule Pooling.

    • Use custom counters. See Custom Counters.

    • Use electronic data interchange (EDI) and EDI receipts. See EDI and Receipts.

    • Use positional and delimited flat files. See Flat-File Positional and Flat-File Delimited.

    In addition, the BTConfigAssistant, which provides simple support for scripted deployment of BizTalk Server Messaging configuration information, has been enhanced to support receive functions.

  • Available business adapters. Connecting disparate systems and accessing heterogeneous data stores is now possible with packaged adapters. Using these adapters to enable access to your systems and data drastically reduces and often eliminates the vast amount of coding required to implement connectivity manually. These adapters connect BizTalk Server 2002 to third-party applications and data, including:
    • Databases

    • File transfer protocol (FTP)

    • Enterprise resource planning (ERP) applications

    • Customer relationship management (CRM) applications

    For a comprehensive list of currently available BizTalk Server adapters available from Microsoft and its partners, go to the BizTalk Server Adapters and Connectivity page on the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/evaluation/adapters.asp).


Who Is BizTalk Server For?

BizTalk Server 2002 solves critical integration problems for a wide-ranging audience, from small shops that rely on sole partnerships for their livelihood, to large manufacturing companies that maintain hundreds of partnerships and handle thousands of documents each second.

Smaller companies might use BizTalk Server for point-to-point connectivity, but for larger corporations, this becomes less efficient. In the largest corporations, multiple BizTalk Server groups can be joined together to form a distributed integration bus. The largest organizations are typically organized into autonomous, discrete business units that develop and maintain their own systems. These business units need to both share data with applications controlled by other business units and communicate with external trading partners.

The following illustration shows how data might be shared within a company that has built its integration architecture piece-by-piece as needs arose. The right side shows how BizTalk Server 2002 helps make data interchange more organized and efficient.

BizTalk Server enables seamless and efficient data integration.

Established companies find that BizTalk Server enables their legacy systems to operate more efficiently and helps them re-tool their architecture for business-to-business e-commerce. A startup company can use BizTalk Server from the beginning as a key link around which to integrate a new system into its enterprise.

Consider these real-world cases:

  • A health care manufacturer uses BizTalk Server to interact with a variety of e-commerce platforms.

  • A privately held company that develops and markets business-to-business e-commerce and process automation solutions for the global business finance market uses BizTalk Server technologies to build an infrastructure that enables data integration to happen seamlessly, less expensively, and more efficiently.

  • A PC manufacturer is using BizTalk Server to rapidly deliver data and documents, and to integrate its supply chain relationships in order to improve its supply chain, increase efficiency, and deliver a smooth, trouble-free experience to customers.

  • A digital marketplace company is using Microsoft Windows 2000, Internet Information Services (IIS), and BizTalk Server, to build an Internet hub that provides one-stop shopping for prospective college students, high school guidance counselors, and university recruiting and admissions departments.

  • A firm that offers a suite of financial and accounting services designed for small- and medium-sized businesses uses XML and BizTalk Server to create Web services based on its internal SAP R/3 application suite.

The following topics are covered in this section:

  • How BizTalk Server Fits into an Organization's IT Infrastructure

  • How BizTalk Server Fits into the .NET Platform


How BizTalk Server Fits into an Organization's IT Infrastructure

What does your company's technical infrastructure look like? Is it built on a single platform of Windows or UNIX? Probably not. Most enterprise companies run a mix of various systems. Even if you have one "standard" platform, you likely have several other application and development environments running simultaneously to help you accomplish your company's business goals.

Because your current configuration is a proven system that represents a substantial investment of your company's time and money, you should not have to replace it just to solve a new business problem. Legacy systems are typically replaced when there is a good business reason to do so.

BizTalk Server provides a central, data-driven, integration server and a set of advanced productivity tools and services that enable you to build and deploy business processes for performing enterprise application integration (EAI) and business-to-business (B2B) transactions. With support for multiple transports and protocols, BizTalk Server helps you enable existing IT investments for XML and incorporate them into new e-commerce technologies.

BizTalk Server enhances your existing IT investments with XML by:

  • Providing BizTalk Mapper, a graphical data-mapping tool for converting XML data to and from legacy data formats with various structures, such as EDI and flat files.

  • Supporting industry-standard transports and protocols, such as HTTP, HTTPS, SMTP, SSL, S/MIME, and SOAP, to integrate your existing IT investments with Web applications and services.

  • Using standard adapters from leading industry vendors to access business applications. For more information, see the BizTalk Server Adapters and Connectivity page on the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/evaluation/adapters.asp).

With minimal hardware and software requirements, BizTalk Server installs into your established IT infrastructure.

For details about BizTalk Server features such as XML tools, BizTalk Messaging Manager, and BizTalk SEED Wizard, see BizTalk Server Features.


How BizTalk Server Fits into the .NET Platform

The Microsoft® .NET platform includes a comprehensive family of .NET-based products built on industry and Internet standards that provide for each aspect of developing (tools), managing (servers), using (building block services and smart clients) and experiencing (rich user experiences) XML Web services.

The .NET Enterprise Servers encompass both e-commerce and overall enterprise infrastructure. The Windows 2000 Server family is Microsoft's secure, scalable foundation for running the .NET Enterprise Servers and e-commerce business applications.

The .NET Enterprise Servers include:

  • Application Center 2000 to deploy and manage highly available and scalable Web applications.

  • BizTalk Server 2002 to build XML-based business processes across applications and organizations.

  • Commerce Server 2000 for building scalable e-commerce solutions.

  • Content Management Server 2001 to manage content for dynamic e-business Web sites.

  • Exchange 2000 Server to enable messaging and collaboration.

  • Host Integration Server 2000 for bridging data and applications on legacy systems.

  • Internet Security and Acceleration Server 2000 for secure, fast Internet connectivity.

  • Mobile Information 2001 Server to enable application support by mobile devices like cell phones.

  • SharePoint Portal Server 2001 to find, share, and publish business information.

  • SQL Server 2000 to store, retrieve, and analyze structured XML data.

Microsoft SQL Server manages your database business logic while Microsoft Commerce Server handles your front-end customer interface.

BizTalk Server is the back-end that powers an e-commerce or back-end enterprise solution. Once the purchasing application, such as Microsoft Commerce Server, facilitates a customer's placing an order for a product, BizTalk Server handles the purchasing process that was previously done manually. BizTalk Server "buys" the product from suppliers, manages the purchase order exchange, and performs internal enterprise application integration (EAI). Once the purchase is confirmed, the customer's records are fed into a finance application, which sends an order ticket to the distribution program.

In addition, Microsoft Host Integration Server and host system adapters provide access to mission-critical data that is stored on a back-end mainframe or minicomputer. Host Integration Server is designed to extract data from a mainframe and transfer it to BizTalk Server or Commerce Server, completing the entire e-business transformation without converting or replacing the mainframe hardware or software.

For more information about .NET Enterprise Servers, go to the Microsoft .NET Enterprise Servers Web site (www.microsoft.com/servers).

For information about BizTalk Framework 2.0, as well as information about BizTalk Server product resources such as community services, a large library of schemas, and white papers, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk).

XML Web services

As e-commerce grows among businesses and consumers, the industry is converging on a new computing model that enables a standard way of building applications and processes to connect and exchange information over the Web. This new Internet-based integration methodology, called XML Web services, enables applications, computers, and businesses to work together in a way never possible before.

The following illustration shows how XML Web services can be leveraged in a number of combinations to create user experiences.

XML Web services enables applications, computers, and businesses to work together.

With the help of XML-based technologies such as SOAP, which enables applications to interoperate with standard Internet protocols, and Universal Description, Discovery, and Integration (UDDI), which gives businesses a standard way to describe their services and connect automatically, developers are creating a new type of software that uses XML to provide Web-based services. (For more information about UDDI, go to www.uddi.org.) XML Web services are flexible technologies that bind disparate systems across different languages, unifying personal computing, enterprise computing, and the Web. These XML Web services are programmable and reusable, much like component software, except that they are accessible anywhere on the Internet. Programs using this model can run across multiple Web sites, drawing on information and services from each of them, and combining and delivering them in customized form to any device.

The Microsoft .NET platform enables you to build, deploy, operate, and integrate XML Web services. The following is a list of the four principles of XML Web services:

  1. Systems must connect through the Internet. This is a safe assumption given the high availability and low-cost connectivity provided by the Internet.

  2. There must be a simple way to find services on the Internet with which businesses can work. UDDI is a broad industry effort, involving several major companies, which provides a way to locate and understand services provided by other companies.

  3. A common language is needed to ensure that information is shared with others. XML is the ingredient that makes this possible. XML provides a common data format so that you can continue to work with data and information in a way that does not require business partners or customers to use a particular programming language, application, or operating system to interact with your systems.

  4. There must be a way to actually conduct business. For example, there has to be a way to call the service, book the appointment, order the part, or deliver the information—through a common protocol. This protocol is called SOAP. It enables systems to talk to one another and make requests. SOAP is the new model for Internet native integration.

These four principles enable you to connect, find, transform, and transact across systems, applications, and processes to deliver XML Web services.

With a graphical interface built into tools such as BizTalk Mapper, BizTalk Editor, and BizTalk Orchestration Designer, BizTalk Server is a key component in architecting XML-based business processes across applications and organizations. To learn more about XML Web services and the Microsoft .NET platform, see www.microsoft.com/net.


How Does BizTalk Server Work?

Microsoft BizTalk Server 2002 consists of two main services: BizTalk Messaging Services through which you send messages between business processes, and BizTalk Orchestration Services through which you create your business processes.

The pain of integration

No question about it, integrating applications within an organization has always been far too painful. You have seen these challenges firsthand—different applications sitting on different operating systems, written in different languages, based on different programming models. And your job is to get them all talking.

The e-commerce world, however, has made integration tasks considerably more complicated. Not only are you faced with integrating your internal systems, you must also integrate their processes with those of external customers and key suppliers—requiring open technologies such as XML Web services, HTTP or SMTP for delivery, and XML for data formatting—and it all has to be done over the Internet.

Companies that want to remain competitive need to do a fundamentally better job with internal and external integration. Historically, the differences between internal and external integration challenges have been seen as different sets of point-to-point connections. But connections are just a means to an end; the real end is integrating business processes.

Internally, businesses typically use proprietary data formats, and have historically employed a synchronous remote procedure call (RPC) mechanism. However, as you integrate more internal applications, the synchronous model leads to concerns about reliability and availability. To counter this, businesses today are moving toward an asynchronous model that appears synchronous—so called "sync on async."

So where do you begin? Business process integration sounds great, but it is often a full-time job just keeping your connections working properly. And at the end of the day, your job is to get the right information in the right place at the right time.

That's where BizTalk Server can help.

BizTalk Server enables you to integrate business processes

Using BizTalk Server, business analysts, IT professionals, and developers can work in a common environment where they can rapidly define, design, and deploy integrated solutions that work across applications, platforms, and organizations.

BizTalk Server makes it easier to orchestrate dynamic business processes within and between organizations.

More specifically, BizTalk Server enables you to:

  • Simplify application integration. Easily build, manage, and track distributed business processes that cross the boundaries of applications, organizations, and time.

  • Decrease time to market. Quickly establish reliable, secure business-to-business (B2B) trading relationships with customers and key partners over the Internet.

  • Leverage existing IT investments. Cost-effectively integrate disparate legacy applications using standards, independent of platform.

The following topics are covered in this section:

  • BizTalk Messaging Services

  • BizTalk Orchestration Services

  • Building a BizTalk Server Solution

  • Manageability, Reliability, Flexibility

  • BizTalk Server Accelerators


BizTalk Messaging Services

BizTalk Messaging Services include:

  • Receiving incoming documents.

  • Parsing the documents to determine their specific format.

  • Extracting key identifiers and identifying specific routing rules.

  • Delivering documents to their respective destinations.

  • Tracking documents.

Also included are services for data mapping, receipt generation and correlation, and services to ensure data integrity and security.

To access code samples that use BizTalk Messaging Services, see BizTalk Messaging Services Code Samples.

Messaging configuration methods

BizTalk Server provides two methods for configuring BizTalk Messaging Services to manage the exchange of documents between trading partners and applications within your business. These methods are:

  • BizTalk Messaging Manager, a graphical user interface that contains a messaging wizard

  • BizTalk Messaging Configuration object model, a model you access directly

Using BizTalk Messaging Manager or the BizTalk Messaging Configuration object model, you can create messaging ports and channels to manage the exchange of data. You can also create document definitions, envelopes, and organizations, which you use to create messaging ports and channels; and distribution lists, which are groups of messaging ports.

Configuring your messaging service

The following illustration shows the steps you take when creating a document specification and configuring your messaging service.

Messaging service configuration process.

You start by using BizTalk Editor to graphically create a document specification, which is an Extensible Markup Language (XML) file that defines a document's structure, type, and version. If your trading partner needs the document in a different format, you can use BizTalk Mapper to map the document's data into a format that your partner can use.

To configure your messaging service, you need to set up a document definition that refers to the specification you created. You do this by accessing the BizTalk Messaging Configuration object model either graphically through BizTalk Messaging Manager, or directly through the application programming interface (API). Conceptually, an XML specification and a BizTalk document definition are identical. From a technical viewpoint, however, they differ greatly in how they are created and stored. Specifications are documents that are created by BizTalk Editor and stored as XML files in the WebDAV repository. Document definitions are objects created by the BizTalk Messaging Configuration object model (either through BizTalk Messaging Manager or the API) and stored in the BizTalk Messaging Management database, a SQL Server database used by BizTalk Server. You can think of a BizTalk Server document definition as an XML specification that has been converted into an object form.

The following topics are covered in this section:

  • Receive functions

  • Transport services

  • Data parsers

  • Data validation

  • Reliable messaging

  • Security

Related Topics

BizTalk Messaging Services Code Samples

Introducing Messaging Services

Using BizTalk Messaging Manager


Receive functions

BizTalk Server 2002 provides receive functions that enable the server to monitor documents posted to specified locations. BizTalk Server supports the following receive functions, which are configured by using BizTalk Server Administration:

  • File

  • HTTP

  • Message Queuing

BizTalk Server 2002 also supports the following inbound protocols, which are configured by using ASP pages or a Microsoft Exchange script:

  • Hypertext Transfer Protocol (HTTP) using an .asp page

  • Secure Hypertext Transfer Protocol (HTTPS) using an .asp page

  • Simple Mail Transfer Protocol (SMTP) using a Microsoft Exchange script

  • File Transfer Protocol (FTP) using the Internet Information Services (IIS) FTP service and a File receive function

Related Topics

Data parsers

Data validation

Receive Functions

Reliable messaging

Security

Transport services


Transport services

BizTalk Server 2002 provides transport services that enable the transmission of documents to their destinations. BizTalk Server supports the following transport services:

  • Hypertext Transfer Protocol (HTTP)

  • Secure Hypertext Transfer Protocol (HTTPS)

  • Simple Mail Transfer Protocol (SMTP)

  • File

  • Message Queuing

  • Application integration components (AICs)

  • Loopback

Related Topics

Data parsers

Data validation

Receive functions

Reliable messaging

Security

Transport Services

Copyright © 1999–2001 Microsoft Corporation.
All rights reserved.

Did you find this information useful? Please send your suggestions and comments about the documentation to BizTalk Server Documentation Feedback@microsoft.com


Data parsers

BizTalk Server 2002 supports data parsers for a variety of industry document standards, such as ANSI X12,EDIFACT, flat files, and valid, well-formed XML . In addition, you can develop, register, and use your own custom parser components.

BizTalk Server also supports BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/).

Related Topics

Data validation

Receive functions

Reliable messaging

Scale Out BizTalk Messaging Services

Security

Transport services


Data validation

BizTalk Server 2002 provides data validation by verifying each instance of a document against a specification. If the document does not adhere to the specification rules, the document is placed into the Suspended queue for further analysis or automated error-correction.

Related Topics

Data parsers

Receive functions

Reliable messaging

Security

Transport services


Reliable messaging

BizTalk Server 2002 provides reliable messaging by using configurable BizTalk Messaging Services properties. These properties include setting service windows for sending documents, sending or receiving receipts, setting the number of retries, and setting the time between retries. BizTalk Server supports the use of BizTalk Framework-compliant envelopes, which provide reliable messaging features. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/). BizTalk Server also queues documents to a central location. In the event of a server failure, rollover mechanisms enable new servers to take control of documents and process them.

Related Topics

Data parsers

Data validation

Receive functions

Security

Transport services


Security

Microsoft BizTalk Server 2002 enables businesses to securely exchange data with trading partners. BizTalk Server takes advantage of the following security features offered through Microsoft Windows 2000 security:

  • Windows Account Security and Local Policies

  • Integrated Windows and Microsoft SQL Server™ Logon Security

  • Microsoft Component Services Security and Roles

  • Public-key infrastructure (PKI)

  • CryptoAPI

  • Smart cards

  • Kerberos protocol

BizTalk Server 2002 supports Secure Multipurpose Internet Mail Extensions (S/MIME) certificate-based public key encryption and digital signatures for all documents that are transmitted using BizTalk Server 2002 transport services. BizTalk Server also supports decryption and signature verification for the documents that it receives.

Related Topics

Data parsers

Data validation

Receive functions

Reliable messaging

Transport services

Understanding Security


BizTalk Orchestration Services

Before you start thinking about BizTalk Orchestration Services, think first about the word "orchestrate." Does music come to mind? The conductor of a musical orchestra takes dozens of musicians and skillfully blends them into a single harmony. Without the conductor, the individual musicians are lost. Have you ever heard 40 different musicians all practicing their instruments before a performance? It's chaos. But once the maestro begins conducting, each of those 40 instruments blends its sound perfectly into the harmony of the orchestration.

That's how BizTalk Server handles your business processes.

A business process determines the logical order of actions

Business-process integration is often developed through understanding the external interfaces that each system exposes, and the message formats and specifications used to transfer messages. Typically, quality of service issues—such as security, message encoding, and reliable messaging—must also be addressed. However, addressing, sending, and receiving messages are not enough to provide a total solution for business-process integration.

How is the original message created? How is a message received, processed, and responded to? In all but the simplest cases, these are business processes. A business process determines the logical order of actions and the corresponding flow of messages, and it defines the message-exchange protocol between the distributed participants.

Most business processes today, perhaps even yours, are created using custom code. As a result, businesses are often constrained from rapidly changing their business-process implementations to reflect the evolving business needs in today's fast-paced environment. BizTalk Orchestration Services solves this problem by removing the custom coding aspect of creating business processes, resulting in an environment that can be changed quickly.

BizTalk Server lets you orchestrate your business processes

BizTalk Orchestration Services represents a new way to approach designing, deploying, and maintaining distributed business processes. BizTalk Orchestration Services are used to design business processes that manage the overall business logic. BizTalk Server lets you orchestrate your business processes by combining a run-time engine with a design-time tool called BizTalk Orchestration Designer. Using BizTalk Orchestration Designer, you visually coordinate all of your business-to-business orchestrations on screen in a Microsoft® Visio® graphical interface. BizTalk Server then saves your workflow in an executable file called an XLANG schedule, which a run-time engine uses to execute your business processes. You do not write any code to bind the business processes together; your coding is in the individual components of specialized business logic, rather than the implementation that holds them together.

BizTalk Orchestration Services include the integration of long-running business processes with the applications that run those business processes. This integration is provided by the XLANG schedule. Additional services provide control for running XLANG schedule instances.

A key feature of BizTalk Orchestration Services is the ability to handle complex transactions that run as long as weeks or months, not just minutes or hours. BizTalk Orchestration Services also enable you to implement concurrent actions within a single XLANG schedule. In addition, you do not need to write custom code to manage the state of your business process; BizTalk Orchestration Services manages it for you.

To access code samples that use BizTalk Orchestration Services, see BizTalk Orchestration Services Code Samples.

The following topics are covered in this section:

  • XLANG schedules

  • Implementation technologies

  • XLANG language

Related Topics

BizTalk Orchestration Services Code Samples

Designing BizTalk Orchestrations


XLANG schedules

An XLANG schedule is a business process implemented by connecting each step in the process to a technology component or service that executes the step. An XLANG schedule is then run by a service called the XLANG Scheduler Engine. The engine controls the instantiation, execution, dehydration, and rehydration of an XLANG schedule, or multiple instances of one or more schedules.

Related Topics

Implementation technologies

XLANG language

XLANG Schedules

Copyright © 1999–2001 Microsoft Corporation.
All rights reserved.

Did you find this information useful? Please send your suggestions and comments about the documentation to BizTalk Server Documentation Feedback@microsoft.com


Implementation technologies

Implementation technologies that are supported by BizTalk Orchestration Services include:

  • BizTalk Messaging Services

  • COM components

  • Message Queuing Services

  • Windows Script Components

  • Microsoft .NET-based components, using Component Object Model (COM) interoperability

Related Topics

Implementing Business Processes

XLANG schedules

XLANG language


XLANG language

XLANG is a language that describes the logical sequencing of business processes, as well as the implementation of the business process by using various technology components or services. The XLANG language is expressed in Extensible Markup Language (XML).

Related Topics

Implementation technologies

XLANG schedules

XLANG Interfaces


Building a BizTalk Server Solution

Before you build your BizTalk Server solution, you need to plan the methodology, that is, you should determine the specific way a solution will perform to ensure the appropriate deliverables are being met.

For example, you might ask the following planning questions:

  • Do you need to deliver documents, receive documents, or both?

  • What documents need to be transferred?

  • To where do they need to be transferred?

  • When do they need to get there?

  • What document format will you use?

  • What protocols will you use to transfer the documents?

  • Are there legacy systems that need to adapt to your new integration system?

  • What kinds of files do those legacy systems require?

The decisions based on these and other questions are traditionally made during the design phase of a project, and then implemented over a period of several weeks or months by a team of programmers. With BizTalk Server, you can use BizTalk Orchestration Designer to rapidly build business processes in the visual designer.

A common scenario for integrating two services is the correlation of messages within a single running XLANG schedule instance. That is, to have an XLANG schedule instance send a message to an internal application or trading partner, and to expect a message in return. An example is sending a purchase order and expecting a purchase order acknowledgement in return.

Using the XML tools provided with BizTalk Server, your development process might follow the sequence described in the following table.

Development task | Traditional method | BizTalk Server method
Diagram the business process. | Sketch out the business process on paper or whiteboard, or use a CASE tool. | Use BizTalk Orchestration Designer to combine geometric shapes and connections into an XLANG schedule drawing.
Implement the business process | Manually write code to resemble the intended business logic. | Bind your XLANG schedule to components to apply meaningful executable code to your drawing.
Design the structure of your documents. | Determine the structure of the documents, convey that information to the programming department, then have them choose a language and manually write code to resemble the document structure. | Create the document specifications using BizTalk Editor.
Synchronize your data with your business partner's data. | Manually write code that will read and write data formats into your document structure. | Visually map your data format to your partner's data format using BizTalk Mapper.
Configure the communication between your company and your business partner. | Manually write code that will transmit and receive documents and messages. If necessary, write code to perform message queuing and configuration. | Create channels and ports using BizTalk Messaging Manager.
Deploy your solution. | Manually configure your system to receive new documents from trading partners, then have your trading partners write code to configure and deploy their systems to work with yours. | Use Microsoft Application Center to deploy inside your enterprise. Then use the BizTalk SEED Wizard to package your configuration and deploy to a trading partner.
Monitor your documents. | Manually write code that will monitor and track documents, create performance statistics, and generate reports on your customized code. | Use Microsoft Operations Manager (MOM) and the Tracking database to monitor alert notifications, create performance statistics, and monitor databases.

RAD for business processes

The concept of rapid application development (RAD) came from the need to create and deploy a software solution quickly to ensure the solution was still relevant by the time it was implemented. The RAD approach, when implemented efficiently, not only reduces development time, but also decreases production costs.

BizTalk Server introduces RAD concepts into inter-company business process development by offering powerful XML tools such as BizTalk Orchestration Designer, BizTalk Editor, and BizTalk Mapper.

BizTalk Server lets you maintain your long-term infrastructure investment while meeting your requirements for short-term critical success.

The following topics are covered in this section:

Enterprise Application Integration

Business-to-Business Integration

Business Process Automation


Enterprise Application Integration

Each application represents a proven, efficient system within an organization. Companies today rely on applications to perform business-critical functions such as ordering supplies, scheduling manufacturing, and fulfilling customer orders. Enterprise application integration (EAI) enables separate applications to share data electronically.

From a messaging standpoint, EAI technologies have adopted a paradigm for integrating applications that creates one-to-many and many-to-one messaging relationships. In these models, applications do not need to be aware of each other. Data can pass into BizTalk Server and be routed to the appropriate applications. This paradigm focuses on integrating applications with the data distribution infrastructure of the business domain instead of integrating applications directly with each other. In the EAI model, applications can be plugged into the business network data bus and the applications can participate in the business process flow without creating tightly coupled dependencies between systems.

BizTalk Server integrates with other applications through its support for open standards such as XML, and legacy file formats such as positional and delimited text files. In many cases, pre-built adapters are available to ease integration between disparate systems. An adapter is a set of APIs that enables you to use the BizTalk messaging engine to facilitate transactions between BizTalk Server and other specified applications. BizTalk Server currently offers adapters for several business applications and more are being developed. Simply put, adapters do the busywork for you. Instead of spending your time writing low-level EAI code, you can concentrate on refining your own unique business processes. For a comprehensive list of currently available BizTalk Server adapters, go to the BizTalk Server Adapters and Connectivity page on the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/evaluation/adapters.asp).

Related Topics

Business-to-Business Integration

Business Process Automation


Business-to-Business Integration

The popularization of the Internet in the 1990s led to the birth of business-to-business (B2B) processes, which allow a company to exchange data with a key partner or customer. It stands to reason that if you want to integrate your business processes with a partner's, you need a compatible document format in which to exchange data.

BizTalk Server transforms and routes data in the form of XML-based messages within and between organizations, including those that use disparate software and hardware platforms.

However, B2B does not replace enterprise application integration (EAI). In fact, the two complement each other. Nearly every transaction between businesses involves two EAI transactions: one to retrieve the document, and the other to transport it to another computer. For example, say you need to transport a purchase order from your back-end system across the Internet to your business partner's back-end system. While B2B will achieve the cross-company transport, you still need EAI implementations to move the purchase order between your back-end system and your front-end server.

BizTalk Server helps you orchestrate the entire process.

Related Topics

Business Process Automation

Enterprise Application Integration


Business Process Automation

Business process automation (BPA) offers a holistic view over the entire development process. This is important because it provides a unified view of the overall process rather than a set of disparate components interacting in a manner that could traditionally only be defined on paper. In the e-commerce world, a process is no longer confined to a single company, but often maximizes its efficiency by spanning across several organizations and systems. BPA takes the intellectual property of a project and embeds it into the software itself, enabling you to quickly understand an existing business process and alter it as required.

Related Topics

Business-to-Business Integration

Enterprise Application Integration


Manageability, Reliability, Flexibility

BizTalk Server provides tools for defining and maintaining business processes managed by the product, as well as taking advantage of the management facilities offered by the Windows 2000 platform.

The following topics are covered in this section:

  • Manageability

  • Reliability

  • Flexibility


Manageability

BizTalk Server provides BizTalk Messaging Manager for defining distributed business processes and managing all application relationships, both internally and with external trading partners.

In addition, BizTalk Server:

  • Provides a Microsoft Management Console (MMC) snap-in for monitoring the critical services and queues that the product relies on.

  • Includes a Windows Management Instrumentation (WMI) provider for low-level access to event information, which then writes the appropriate entries to the Windows Event Log.

  • Exposes key attributes as performance counters to enable personnel familiar with the Windows 2000 environment to monitor and manage activity in the server.

  • Provides a Web-based interface for querying the data tracking and analysis subsystem to find and access data that represents the resulting business activity that has flowed through the product.

You can also use Microsoft Operations Manager (MOM) 2000 and Microsoft Application Center 2000 to monitor BizTalk Server activity.

Microsoft Operations Manager

Microsoft Operations Manager (MOM) 2002 is an event collection, performance monitoring, and reporting tool for Microsoft server operating systems and server-based applications. MOM centrally monitors, manages, and secures a wide range of resources, improving the availability, performance, and security of Windows 2000 networks and applications by providing proactive real-time system monitoring.

MOM provides the following features:

  • Event-driven operations monitoring

  • Self-deploying, scalable solutions

  • Advanced security policy enforcement and auditing capabilities

  • Improved system availability and performance tracking

  • Numerous ways to view and report data

Microsoft Application Center 2000

Microsoft Application Center can be used to deploy a BizTalk Server configuration from one environment to another, such as moving a configuration from a test environment to a production environment. Using Application Center to deploy environments greatly reduces both the time it takes to move configurations and the amount of manual intervention associated with such a move.

Related Topics

About Microsoft Operations Manager

Flexibility

Reliability

Using Application Center 2000

Using Application Center for E-Procurement Deployment


Reliability

BizTalk Server 2002 has been built to handle the most demanding processing requirements. Specifically, BizTalk Server operates on a "shared queue" concept, where multiple servers can pull work from a central queue for processing. All work to be processed is submitted into a single queue (that can be clustered on the back-end for fault tolerance), technically in Microsoft SQL Server, which is then drawn from by one or more processing servers.

If higher scalability is required, servers can be added to the processing array. When BizTalk Server is installed, it can join a server group by pointing it to the shared queue. This allows a highly scalable "scale out" scenario, whereby for small processing loads only one or two servers may be handling the load, but for scalability requirements that require millions of documents per day to be processed, you can add five, ten, or even more servers to the server array. For higher scale-up on one server or multiple cooperating servers, Windows 2000 Datacenter Server supports the use of BizTalk Server on systems up to 8 CPUs.

Built-in redundancy

An important distinction must be made between redundant servers, which do not persist any data on their local hard disks, and servers that do persist data. BizTalk Server already provides redundancy and scalability by allowing all the servers within a group to access a single BizTalk Server database server over the network. If one of the servers in the group fails, the others take over and continue to access the database server. This is possible because none of the servers in the group persist working data to their local disks. However, if the remote database server becomes unavailable, all servers in the group will be rendered inactive. For full-time availability, use Microsoft Cluster service, which ensures that the central database server is always available even if there is a single server failure.

The decision to use the Cluster service depends on two factors:

  • The downtime that your business can tolerate when a server that persists important data to a local disk becomes unavailable.

  • The budget you have available for the additional hardware and software to provide satisfactory redundancy.

At least two servers are required for simple redundancy.

Related Topics

Manageability

Flexibility


Flexibility

BizTalk Server is an example of applying Internet-standard technologies to solve your integration needs. BizTalk Server was designed with support for:

  • Extensible Markup Language (XML)

  • Hypertext Transfer Protocol (HTTP)

  • Secure Hypertext Transfer Protocol (HTTPS)

  • Simple Mail Transfer Protocol (SMTP)

  • Secure Sockets Layer (SSL)

  • Secure Multipurpose Internet Mail Extensions (S/MIME)

  • SOAP

  • x509v3 certificates

BizTalk Server can be extended through plug-in components and software development kits (SDK). In addition, support for key XML-based standards throughout the product provide integration with applications on other systems, independent of operating system, programming model, or programming language.

Accelerators and adapters

BizTalk Server supports XML and many non-XML data formats, such as electronic data interchange (EDI) and flat files. However, it can support any esoteric file and envelope format through the use of custom serializers and parsers, which you can get as part of industry accelerators or create them using the BizTalk Server Developer's Toolbox. For more information, see BizTalk Server Accelerators.

BizTalk Server supports several pre-built third-party adapters to ease integration between disparate systems. An adapter is a set of APIs that enables you to use the BizTalk messaging engine to facilitate transactions between BizTalk Server and other specified applications. For a comprehensive list of currently available BizTalk Server adapters, go to the BizTalk Server Adapters and Connectivity page on the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/evaluation/adapters.asp).

Transport protocols, functoids, and architecture

BizTalk Server natively supports many leading transport protocols such as DCOM, Message Queuing, HTTP, HTTPS, SMTP, and FTP. In addition, BizTalk Server supports the MQSeries and SNA protocols through the Host Integration Server 2000 plug-in and MQSeries adapter.

BizTalk Server allows for documents to be transformed using conversion functions called functoids, which can be created and reused. A comprehensive set of functoids is provided in BizTalk Mapper, and custom functoids can be created using the BizTalk Server Developer's Toolbox.

The BizTalk Server architecture allows the appropriate combination of database, receive, and processing servers to be used to handle processing requirements.

XML and XML-related technologies

BizTalk Server supports XML to provide open integration with applications on various platforms.

In addition, BizTalk Server:

  • Uses XML as its internal canonical format.

  • Uses XML Document Object Model for accessing documents in memory.

  • Supports XPath for accessing XML document nodes.

  • Uses Extensible Stylesheet Language Transformation (XSLT) as the standard for converting document formats.

  • Supports XML namespaces for semantic clarity.

  • Uses XML schema technologies (through the use of XML-Data Reduced (XDR), a functional subset of XML schema) for data typing, namespace support, and an extensible model.

Related Topics

Manageability

Reliability


BizTalk Server Accelerators

Microsoft offers accelerators that can significantly increase the development and performance of BizTalk Server 2002 installations in specific markets and industries.

Microsoft currently offers BizTalk Server accelerators for:

  • Health insurance standards: BizTalk Accelerator for HIPAA

  • Multiple supply channels: BizTalk Accelerator for Suppliers

  • Supply chain standards: BizTalk Server Accelerator for RosettaNet


BizTalk Accelerator for HIPAA

Microsoft BizTalk Accelerator for HIPAA streamlines the development and deployment of integration solutions for data exchange that is consistent with the transaction standard regulations of the Health Insurance Portability and Accountability Act of 1996 (HIPAA). HIPAA was enacted primarily to improve the portability and continuity of individual and group health insurance coverage in the United States. HIPAA mandates that health care organizations comply with HIPAA guidelines when they transmit information electronically. The goal of HIPAA is to reduce health care costs without impacting providers. Today, there are over 400 different transmission formats with different content for just one of the HIPAA transactions, the health care claim. After HIPAA is instituted (currently slated for October 16, 2002), there will be one content set and one format that all payers must accept.

Microsoft, in conjunction with Washington Publishing Company (WPC), domain expert and exclusive publisher of the HIPAA implementation guides (www.wpc-edi.com/hipaa), is offering BizTalk Accelerator for HIPAA. This accelerator helps the health care insurance industry build standards-based technology solutions and reduce the amount of time and money that organizations need to spend to comply with HIPAA regulations. Health care and allied organizations affected by HIPAA can use the integration capabilities of BizTalk Server 2002, along with HIPAA resources provided by WPC, to automate business processes and quickly build integration solutions. This helps them to comply with federal law while leveraging existing IT investments. The interoperability of BizTalk Server 2002 with health care and allied organizations' legacy systems, combined with the BizTalk HIPAA schemas, provides the industry with the tools to meet the HIPAA mandate.

For more information about BizTalk Accelerator for HIPAA, go to the Microsoft for Partners Web site (www.microsoft.com/Partner/products/serverproducts/biztalkserver2000/btshipaafinal.asp).


BizTalk Accelerator for Suppliers

Microsoft BizTalk Accelerator for Suppliers provides an extensible software solution that enables suppliers to sell more effectively through multiple online channels. The accelerator is built on an extensible architecture, giving organizations the ability to connect to their business-to-business (B2B) trading partners as well as internal line-of-business applications such as an enterprise resource planning (ERP) system, a supply chain management system, or a customer relationship management (CRM) system. Pre-built Web pages make it easy for suppliers to create a unique Web experience for customers while leveraging remote shopping standards.

BizTalk Accelerator for Suppliers offers:

  • Increased revenue and business agility. With Biztalk Accelerator for Suppliers, a company can increase revenue and strengthen relationships with existing customers while lowering trading costs incurred by non-electronic processes. Companies can also become more agile by providing an efficient way to enter new markets and respond to market changes in a timely manner. In addition, businesses can interact with new selling channels and capabilities based on the various technologies, protocols, data formats, and business processes provided in the accelerator.

  • An opportunity to differentiate yourself from the competition. BizTalk Accelerator for Suppliers gives companies the ability to expose the supplier's full value proposition and brand in an electronic medium. Companies can lower costs and accelerate the process of acquiring new customers while increasing the business with an existing customer base.

  • Reduced costs and ability to leverage existing investments. Enhance and compliment existing business processes and technology investments such as ERP, supply chain, CRM, logistics, and collaboration.

For more information about BizTalk Accelerator for Suppliers, go to the Microsoft evaluation Web site (www.microsoft.com/biztalk/evaluation/suppliers/default.asp).


BizTalk Server Accelerator for RosettaNet

Microsoft BizTalk Server Accelerator for RosettaNet includes several applications that enable users to develop, administer, and test RosettaNet standards-compliant Partner Interface Process (PIP) implementation XLANG schedules. There are two additional applications for schema management and messaging configuration. This solution provides the application adapters and server platform necessary to build RosettaNet-based solutions that will integrate applications, connect trading partners in supply chains, and enable the orchestration of complex, collaborative business processes.

The applications contained in BizTalk Server Accelerator for RosettaNet, combined with BizTalk Server 2002, enable users to streamline supply chain practices and to collaborate with trading partners and suppliers using the RosettaNet standard. The following list outlines the BizTalk Server Accelerator for RosettaNet applications:

  • PIP Administrator. This application contains all the password information for the database and enables users to specify the location of the XLANG schedules.

  • PIP XLANG Schedule Tester. This application enables users to test XLANG schedules.

  • PIP Schema Manager. This application is used to merge document specifications.

  • Messaging Configuration Wizard. This application enables users to set up organizations as trading partners. It generates configuration scripts, which programmatically invoke BizTalk Messaging Configuration objects to create and configure the required ports and channels.

For more information about BizTalk Server Accelerator for RosettaNet, go to the Microsoft for Partners Web site (www.microsoft.com/Partner/businessresources/SalesResources/factsheets/BTSRosettaNET.asp.


BizTalk Server Features

The following table provides information about BizTalk Server features and how to use them.

Feature Function
Administration
  • Administering Servers and Applications

  • BizTalk Orchestration Services
  • Create and manage servers and server groups.

  • Configure global server group properties, such as the location for the Shared Queue database and the Tracking database.

  • Configure server settings.

  • Configure and manage receive functions.

  • View and manage document queues.

  • Programmatically access the XLANG Scheduler System Manager, group managers, XLANG schedule instances, and XLANG ports.
Document Tracking
  • Tracking Documents
  • Track the progress of documents processed by Microsoft BizTalk Server 2002.

  • Search for, display, view, and save complete copies of any interchange or document processed by BizTalk Server 2002.

  • Create queries to extract essential information from the Tracking database in an easy-to-view format.

  • Extract, store, and analyze important user-defined data from within documents.
Orchestration Design
  • Designing BizTalk Orchestrations
  • Create drawings that describe business processes, and programmatically implement these drawings within an integrated design environment.

  • Compile XLANG schedule drawings into XLANG schedules.

  • Define the flow of data between messages within business processes.
Messaging
  • Using BizTalk Messaging Manager

  • Understanding Messaging Services
  • Manage the exchange of data locally or remotely using BizTalk Messaging Manager.

  • Manage the exchange of data programmatically using the BizTalk Messaging Configuration object model.

  • Create and manage channels, messaging ports, document definitions, envelopes, organizations, and distribution lists.
XML Tools
  • Using BizTalk Editor

  • Using BizTalk Mapper
  • Create and manage document specifications.

  • Create records and fields, and set their properties.

  • Map records and fields from a source specification to records and fields of a destination specification.

  • Use functoids to implement powerful data-transformation functionality.
Deployment
  • BizTalk SEED Wizard
  • Rapidly enable your trading partners by using SEED packages to make your configurations available through the Internet.


BizTalk Server Application Model

Microsoft BizTalk Server 2002 provides tools and services that enable you to create executable applications for controlling your business processes and the exchange of data between trading partners and applications within your business. For a list of the features provided by BizTalk Server 2002, see BizTalk Server Features.

Integrating BizTalk Orchestration Services and BizTalk Messaging Services enables you to control the exchange of documents and messages between your trading partners and internal applications by using multiple transport services. It also provides:

  • Control over complex, long-running transactions and business processes.

  • Reliable delivery of documents and messages.

  • Data validation by verifying each document instance against a specification.

  • Data mapping by using maps to transform document structure and format.

  • Data security and integrity by using encryption and digital signature certificates.

  • Receipt generation and correlation support.

For more information about configuring BizTalk Server to send or receive receipts, see Understanding Receipts.

For more detailed information about how you can integrate BizTalk Orchestration Services and BizTalk Messaging Services, see Integrating BizTalk Services.


BizTalk Server Administration Model

The following table describes the four main areas of administration in Microsoft BizTalk Server 2002 and relevant administrative functions of each area.

Area of administration Administrative function overview
Server administration
  • Configure and manage server groups and servers.

  • Configure and manage receive functions.

  • Manage queues.
Application administration
  • Configure and manage the COM+ applications that host XLANG schedules.

  • Configure and manage the default XLANG Scheduler application.
Programmatic administration
  • Configure XLANG system managers, XLANG group managers, XLANG schedule instances, and XLANG ports.
Database administration
  • Configure, manage, and maintain the following databases:
    • BizTalk Messaging Management

    • Orchestration Persistence

    • Tracking

    • Shared Queue

Server administration

In BizTalk Server 2002, server administration includes tasks such as managing and configuring server groups, adding, deleting and configuring servers, adding and configuring receive functions, and managing the shared queue for each server group. The following table describes the general server administrative tasks, their description, and where to find more information.

Administrative task Description Where to find more information
Configure servers and server groups
  • Configure the connections for the Tracking and Shared Queue databases.

  • Configure transport services and parser order.

  • Configure server settings.
  • Add, Delete, and Configure a Server Group

  • Add, Delete, and Configure Servers in a Group
Manage queues
  • Delete and resubmit interchanges and documents.

  • View data and error messages.
  • Manage Queues
Manage receive functions
  • Configure receive functions.
  • Manage Receive Functions for a Server Group
Troubleshooting
  • Troubleshoot server and document processing problems.
  • Manage Event Viewer

  • Troubleshooting BizTalk Server Administration

Application administration

Application administration includes configuring and managing the COM+ applications that host XLANG schedules, the default XLANG Scheduler application, and the Orchestration Persistence database that is created when you install BizTalk Server 2002. The following table describes the general application administrative tasks, their description, and where to find more information.

Administrative task Description Where to find more information
Manage the default XLANG Scheduler application
  • Change the default settings for the XLANG Scheduler application.
  • Manage the Default XLANG Scheduler Application and Database
Manage COM+ applications
  • Create COM+ applications to run specific XLANG schedules.
  • Manage Other COM+ Applications That Host XLANG Schedules

Programmatic administration

The management and administration of servers and applications can be done programmatically in Microsoft BizTalk Server 2002. The following table describes the general programmatic administrative tasks, their description, and where to find more information.

Administrative task Description Where to find more information
Configure and manage the XLANG Scheduler System Manager, group managers, XLANG schedule instances, and XLANG ports
  • Start, stop, and retrieve information about the XLANG Scheduler System Manager and group managers.

  • Stop, suspend, resume, and retrieve information about all the schedules associated with a group.
  • BizTalk Orchestration Services
Create application integration components (AIC)
  • Create custom components.

  • Integrate line-of-business (LOB) applications.

  • Add encryption, decryption, and digital signature features.
  • BizTalk Custom Components
Use documents and interchanges
  • Access the Suspended queue.

  • Read the Tracking database.

  • Submit documents.

  • View interchange and document data.
  • BizTalk Documents

  • Documents and WMI

  • Displaying the Contents of a Document or an Interchange

  • WMI Tasks
Manage file receive services
  • Perform file receive functions such as create, delete, and retrieve.
  • Receive Services and WMI

  • WMI Tasks
Manage queues
  • Retrieve queues by group.

  • Retrieve all queues.
  • Queues and WMI

  • WMI Tasks
Manage server groups
  • Perform server group functions such as create, delete, and retrieve.
  • Groups and WMI

  • WMI Tasks
Manage servers
  • Perform server functions such as create, delete, start, stop, and retrieve.
  • Servers and WMI

  • WMI Tasks
Manage the BizTalk Messaging Management database
  • Create and retrieve the BizTalk Messaging Management database.
  • BizTalk Messaging Management Database and WMI

  • WMI Tasks
Manage trading partner relationships
  • Set up messaging ports and channels for the exchange of data.

  • Create document definitions and envelopes.

  • Set organization properties.
  • BizTalk Messaging Services

For more information about using Windows Management Instrumentation (WMI) and WMI Application programming, go to the MSDN Online Library (msdn.microsoft.com/library/default.asp) and search for "WMI Application Programming."

Database management

In addition to regular database maintenance and administration, such as compressing data files and backing up the database and transaction file logs, you must perform other database-related tasks, such as maintaining connectivity between BizTalk Server and Microsoft SQL Server, adding, deleting, and restoring databases, and configuring new databases. The following table describes general database administrative tasks, their description, and where to find more information.

Administrative task Description Where to find more information
Manage databases
  • Configure and/or change the BizTalk Messaging Management database.

  • Create and configure new persistence databases.

  • Restore and/or manually remove the Tracking and Shared Queue databases.
  • Configure the BizTalk Messaging Management database

  • Change the BizTalk Messaging Management database for a server

  • Create a new empty persistence database

  • Manage Databases for a Server Group
Monitor traffic to the databases
  • Configure server settings.
  • Understanding Server Properties

  • Optimizing Server Properties


Using BizTalk Server 2002 Help

This section includes information about the Microsoft® BizTalk™ Server 2002 Help system.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Server 2002 Help, see About Help.

  • For detailed procedures on how to accomplish tasks, see How to Perform Help Tasks.


About Help

The Microsoft BizTalk Server 2002 Help system uses HTML to format and display information. The Help Viewer provides an integrated table of contents, an index, and a full-text search feature so that you can find information easily. Book icons open to reveal sub-books and topics. To expand the table of contents and view topics within a book, click the expand indicator (+) next to a book title. When you click the collapse indicator (-), the topics are hidden. The Help Viewer also enables you to see the table of contents, index, or search results at the same time you are viewing a Help topic.

The Help Viewer includes the Favorites tab, which you can use to bookmark topics. This enables you to quickly display topics that you refer to often.

To learn more about BizTalk Server 2002, you can use the table of contents to browse through the documentation. When you click a topic in the table of contents, information is displayed in the content pane of the Help window.

The table of contents is organized in books according to the major features and functions that BizTalk Server 2002 provides. Each book contains some or all of the following chapters:

  • About <feature/function/related concept>. These chapters contain descriptions and general information about BizTalk Server 2002, its features, and related concepts.

  • Why Perform <feature/function name> Tasks. These chapters contain quick references about why you perform specific tasks.

  • How to Perform <feature/function name> Tasks. These chapters contain procedural and task-based information.

  • Troubleshooting <feature/function name>. These chapters contain problem-solving instructions.

For programming information, see BizTalk Server 2002 Developer Solutions.

Related Topics

Find a Help Topic

Help Viewer Shortcut Keys


How to Perform Help Tasks

You can use the tasks described in this section to locate information in Microsoft BizTalk Server 2002 Help. For example, you can locate information by performing a search in Help and then bookmark that information by adding it to a list of your favorite Help topics on the Favorites tab. You can copy information from Help into a different document or print it out. You can also change the font size, so that the content is easier to read.

The following procedures are covered in this section:

  • Find a Help Topic

  • Copy a Help Topic

  • Print a Help Topic

  • Change the Font Size

  • Help Viewer Shortcut Keys


Find a Help Topic

In the Help Viewer, the following tabs provide browse and search options:

  • Contents tab

  • Index tab

  • Search tab

  • Favorites tab

Contents tab

You can use the Contents tab to navigate through Help and learn more about BizTalk Server 2002.

  1. To browse through the table of contents, click the Contents tab.

  2. Double-click the book icons to reveal topic entries and sub-books.

  3. Click a table-of-contents entry to display the corresponding topic.

Index tab

You can use the Index tab to search Help by subject and then display the corresponding topics.

  1. To see a list of index entries, click the Index tab and then either type a word or scroll through the list.

    Topics are often indexed under more than one entry.

  2. Double-click an index entry to display the corresponding topic.

    —Or—

    Double-click a top-level index entry, where there are nested entries, to display a list of all the topics that contain that word.

    The Topics Found dialog box appears.

    Click the topic you want to see and click Display.

Search tab

You can use the Search tab to locate every occurrence of a word or phrase in Help.

  1. To locate every occurrence of a word or phrase, click the Search tab, type the word or phrase for which you want to search, and then click List Topics.

    To improve the search results, you can use the search parameters listed in the following table.

    Use To search for Example
    AND, OR, NEAR, or NOT Multiple words or phrases. This will find combinations of words, and also can be used to exclude words. Messaging AND Orchestration

    Note

    • You can click the right-arrow icon next to the Type in the word(s) to search for box and select an option from the drop-down list.
    Asterisk (*) Any word that starts with the letters before the asterisk. This will find words with different endings. Admin*

    Specif*
    Quotation marks ("") A phrase or a term that contains multiple words. This will eliminate matches for the individual words. For example, if you type "BizTalk Mapper" it will not find all the matches for "BizTalk" and all the matches for "Mapper," only the matches for both words together. "BizTalk Mapper"

    "delimited flat file"

    You can also select the options at the bottom of the Search tab to refine your search:

    • Search previous results. Searches the current list in the results pane with the new search parameters you provide.

    • Match similar words. Searches for all variations on the word being searched for. For example, searches for "messaging" will also return matches to "messages." This option is selected by default.

    • Search titles only. Searches only the titles of the books, sub-books, and topics, not the entire text.
  2. Double-click a search results entry to display the corresponding topic.

Note

  • The words or phrases you search for will be highlighted in the text of the topic being displayed. You can turn off this feature by selecting Search Highlight Off on the Options menu.

Favorites tab

You can create a list of your favorite or most frequently visited Help topics by creating bookmarks for them on the Favorites tab.

  1. To bookmark a topic, use the Contents, Index, or Search tab to locate and then display a topic.

  2. Click the Favorites tab and click Add to save the topic title to the Topics list.

The Help Viewer adds the topic title to the Topics list. Later, you can return to this list and double-click the bookmark to quickly display the topic.

Note

  • To remove a bookmark from the Topics list, click the bookmark and click Remove.

Related Topic

Help Viewer Shortcut Keys


Copy a Help Topic

  1. In the topic pane of the Help Viewer, right-click inside the topic you want to copy and click Select All.

  2. Inside the topic, right-click again and click Copy.

    This copies the topic to the Clipboard.

  3. Open the document to which you want to copy the topic.

  4. Click the place in your document where you want the information to appear.

  5. On the Edit menu, click Paste.

Notes

  • If you want to copy only part of a topic, select the part you want to copy, right-click the selection, and then click Copy.

  • Step numbers are not copied to the Clipboard.

Related Topics

Find a Help Topic

Print a Help Topic


Print a Help Topic

  1. On the Contents tab, select a topic.

  2. On the toolbar, click Print.

    The Print Topics dialog box appears.

  3. Click Print the selected topic to print a single topic and click OK.

    -Or-

    Click Print the selected heading and all subtopics to print all the topics in a book and click OK.

    The Print dialog box appears.

  4. Click Print.

Important

  • It is recommended that you select Landscape for the page orientation because pages with code samples, large illustrations, and significant text might print only partially if you use Portrait orientation. To select Landscape, in the Print dialog box, click the Layout tab and click Landscape in the Orientation area.

Related Topics

Find a Help Topic

Help Viewer Shortcut Keys


Change the Font Size

You can increase the font size of text for easier viewing, or you can decrease the font size to see a representation of the layout of a page.

  • On the toolbar, click the Font ( Font button) button to increase or decrease the text size.

Changes to the font size are retained when you close the Help file, so that the next time you open the Help file, it will display the font size you selected last.


Help Viewer Shortcut Keys

You can use shortcut keys to accomplish tasks in the BizTalk Server 2002 Help Viewer. The following table is a quick reference to the shortcut keys available in the Help Viewer.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Microsoft® Windows® 2000 Server Help, see "Using the keyboard to move the mouse pointer." In Windows 2000 Professional Help, see "To move the mouse pointer by using MouseKeys."

Help Viewer shortcut keys

Press | To
ALT+SPACEBAR | Display the system menu.
SHIFT+F10 Display the Help Viewer shortcut menu.

Note

  • Use this shortcut when the focus is in the topic pane.
ALT+TAB | Switch between the Help Viewer and other open windows.
ALT+O | Display the Options menu.
ALT+O, and then press T | Hide or show the navigation pane.
CTRL+TAB | Switch to the next tab in the navigation pane.
CTRL+SHIFT+TAB | Switch to the previous tab in the navigation pane.
UP ARROW | Move up one topic in the table of contents, index, or search results list.
DOWN ARROW | Move down one topic in the table of contents, index, or search results list.
PAGE UP | Move up one page in the table of contents, index, or search results list.
PAGE DOWN | Move down one page in the table of contents, index, or search results list.
F6 | Switch focus between the navigation pane and the topic pane.
ALT+O, and then press R | Refresh the topic that appears in the topic pane.
UP ARROW or DOWN ARROW | Scroll through a topic.
CTRL+HOME | Move to the beginning of a topic.
CTRL+END | Move to the end of a topic.
CTRL+A | Highlight all text in the topic pane.
ALT+O, and then press P | Print a topic.
ALT+O, and then press B | Move back to the previously viewed topic.
ALT+O, and then press F | Move forward to the next (previously viewed) topic.
TAB Move between related topics.

Note

  • Use this shortcut when the focus is in the topic pane.
ALT+F4 | Close the Help Viewer.

Contents tab shortcut keys

Press | To
ALT+C | Display the Contents tab.
RIGHT ARROW | Open a book.
LEFT ARROW | Close a book.
BACKSPACE | Return to the previous open book.
UP ARROW or DOWN ARROW | Select a topic.
ALT+LEFT ARROW | Move back to the previously viewed topic.
ALT+RIGHT ARROW | Move forward to the next (previously viewed) topic.
ENTER | Display the selected topic.

Index tab shortcut keys

Press | To
ALT+N | Display the Index tab.
UP ARROW or DOWN ARROW | Select a keyword in the list.
ALT+D or ENTER | Display the associated topic.

Search tab shortcut keys

Press | To
ALT+S | Display the Search tab.
ALT+L | Start a search.
ALT+D or ENTER | Display the selected topic.

Favorites tab shortcut keys

Press | To
ALT+I | Display the Favorites tab.
ALT+A | Add a topic to the Topics list.
ALT+P Select a topic in the Topics list.

Note

  • Use this shortcut when the focus is in the topic pane and you want to move to the Topics list.
ALT+R | Remove a topic from the Topics list.
ALT+D | Display a topic from the Topics list.

Related Topic

About Help


Accessibility for People with Disabilities

Microsoft is committed to making its products easier for everyone to use. For information about features that make Microsoft® BizTalk™ Server 2002 more accessible, see the following:

  • Help Viewer Shortcut Keys

  • BizTalk Server Administration Shortcut Keys

  • BizTalk Document Tracking Shortcut Keys

  • BizTalk Orchestration Designer Shortcut Keys

  • BizTalk Messaging Manager Shortcut Keys

  • BizTalk Editor Shortcut Keys

  • BizTalk Mapper Shortcut Keys

Notes

  • For more information about accessibility options, in Microsoft Windows® 2000 Server Help, in the Getting Started with Windows 2000 book, see "Accessibility for People with Disabilities." In Windows 2000 Professional Help, see the chapter "Accessibility for Special Needs."

  • For information about accessibility options in a variety of Microsoft products, go to the Microsoft Accessibility Web site (www.microsoft.com/enable/).


Contacting Microsoft Product Support Services

Product name: Microsoft® BizTalk™ Server 2002

Support options: To get the latest information about your support options, go to the Microsoft Product Support Services Web site (support.microsoft.com/directory/productsupportoption.asp).

  • Worldwide support: Options, hours, and cost in your country/region may differ from the United States; check with your local office for details.

  • Conditions: Microsoft Product Support Services are subject to Microsoft's then-current prices, terms, and conditions, which are subject to change without notice.


Learning to Use BizTalk Server 2002

This section contains three end-to-end scenarios that will help you learn how to use and better understand Microsoft® BizTalk™ Server 2002 tools and services:

  • The BizTalk Server 2002 Tutorial is a traditional tutorial that walks you through the procedures that are necessary to configure a complete business-to-business automated procurement process. This tutorial focuses on giving you the opportunity to learn how to use BizTalk Mapper, BizTalk Editor, BizTalk Orchestration Designer, BizTalk Messaging Manager, and BizTalk Server Administration.

  • Learning BizTalk Server 2002 is a conceptual overview of the fundamental concepts that surround the processes and tasks required to build a business-to-business automated procurement process with BizTalk Server. This approach enables you to run scripts that perform the setup for you. It gives you an opportunity, through exploration, to better understand how the services and processes work.

  • The E-Procurement Sample is an end-to-end sample that demonstrates some of the newest features of BizTalk Server. It provides an overview of the BizTalk SEED Wizard, Application Center deployment, and advanced monitoring capabilities using Microsoft Operations Manager (MOM). It also includes new XLANG correlation using common queues instead of per-instance queues.


BizTalk Server 2002 Tutorial

Business-to-Business Automated Procurement

In this tutorial you will learn how to configure Microsoft® BizTalk™ Server 2002 to establish and run a business-to-business automated procurement process.

You will also learn how BizTalk Server components and services work together to integrate loosely coupled, long-running business processes, both within and between businesses.

Note

  • The BizTalk Server 2002 tutorial is also provided in Microsoft Word format. To print the tutorial, you must use the Word version. If you do not have Word installed, you can view the file by using WordPad or Microsoft Word 97/2000 Viewer. The Tutorial.doc file is located in \Program Files\Microsoft BizTalk Server\Documentation on the BizTalk Server installation drive.

Requirements

To successfully complete this tutorial, you must install BizTalk Server 2002 and all its dependencies. In addition, Microsoft Visual Basic® 6.0 is required to complete portions of the Appendix. For a complete list of the hardware and software requirements for BizTalk Server 2002, see Installing BizTalk Server 2002.

Scenario

The scenario used in this tutorial provides a comprehensive overview of the key elements of BizTalk Server 2002, as well as step-by-step instructions about how to use Biztalk Server tools and services.

In this scenario, Northwind Traders (referred to in this tutorial as the buyer) uses BizTalk Server 2002 to design and implement a business-to-business automated procurement process with Contoso, Ltd (referred to in this tutorial as the seller). When a purchase order request is generated by Northwind Traders, it must meet certain criteria for approval. If the purchase order request is equal to or less than $1,000, a purchase order is generated and sent to Contoso, Ltd. Otherwise, the purchase order request is declined and the process terminates. Northwind Traders automates this process by using an XLANG schedule to control the flow of messages through their system.

After the purchase order request is approved, the buyer's system uses BizTalk Messaging Services to receive, route, and transform the purchase order to match the Contoso, Ltd format, and then extracts the data. The seller (Contoso, Ltd) fills the order and sends an invoice back to the buyer (Northwind Traders). When the buyer receives the invoice, a payment is issued and sent to the seller.

This procurement process is automated by using BizTalk Server 2002 tools and services. Both systems also use a number of auxiliary components that work in conjunction with BizTalk Server 2002 to perform key data-processing tasks.

The following illustration shows the interaction of the business-to-business automated procurement system implemented by Northwind Traders and Contoso, Ltd. Arrows denote the flow of data among roles and entities.

Important

  • For the purposes of this scenario, both the buyer and seller systems are configured on a single installation of BizTalk Server 2002.

The following illustration shows the movement of the documents through the buyer and seller systems. It also shows the interaction between the XLANG schedule, BizTalk Messaging Services, and the auxiliary components. This illustration is a useful reference that you might want to print and have available because it is referred to in several procedures throughout the modules in this tutorial.

Overview of buyer and seller systems

Contents

Module 1: Modeling Business Processes

In this module, you learn how to:

  • Use BizTalk Orchestration Designer to create an XLANG schedule drawing that defines and implements the procurement processes for Northwind Traders. For more information, see Designing BizTalk Orchestrations.

  • Compile the XLANG schedule drawing into an XLANG schedule. For more information, see Compile an XLANG schedule drawing into an XLANG schedule.

  • Run the XLANG schedule to see how a message moves through the buyer system.

Module 2: Creating Specifications and Maps

In this module, you learn how to:

  • Use BizTalk Editor to create document specifications. For more information, see Create and Validate Specifications.

  • Use BizTalk Mapper to create maps. For more information, see Create new maps.

Module 3: Configuring BizTalk Messaging Services

In this module, you learn how to:

  • Use BizTalk Messaging Manager to configure BizTalk Messaging Services for Contoso, Ltd. For more information, see Using BizTalk Messaging Manager.

  • Use BizTalk Server Administration to create a File receive function for Contoso, Ltd. For more information, see Add a File receive function.

Module 4: Completing the XLANG Schedule

In this module, you learn how to:

  • Implement a port in the XLANG schedule drawing that you started in Module 2 by using a BizTalk Messaging implementation. For information about the differences between ports and messaging ports, see Understanding Port Implementations and Understanding Messaging Ports.

  • Complete the XLANG schedule drawing and compile it into an XLANG schedule.

  • Run the schedule to understand the complete movement of messages between the buyer and seller systems.

Shortcuts

  • Throughout this tutorial, several shortcuts are available that will enable you to save time and effort by using an existing XLANG schedule, a document specification, a map, or a configuration script. By using shortcuts, you can advance to subsequent sections of the tutorial.

  • To use shortcuts, all the tutorial components must be installed on drive C. You will not be able to execute the tutorial if you use a different drive.

Continue to Preliminary Setup.


Preliminary Setup

Before you begin the tutorial, you must create the following:

  • One folder containing four subfolders

  • Two local Web site folders containing Active Server Pages (ASP) files

  • Two message queues for the buyer system

Continue to Create folders.


Create folders

In this procedure, you create one folder that contains four subfolders. You use two of the subfolders, Buyer and Seller, as locations for messages as they move into and out of the buyer and seller systems. The other two are content folders for the buyer and seller Web sites.

To create the folders:

  1. In Windows® Explorer, browse to the root directory of your C drive.

    Important

    • You must create the following folders on your C drive. You will not be able to execute the tutorial if you use a different drive.
  2. Create a new folder on the root of your C drive; name the folder TutorialFiles.

  3. Click the new TutorialFiles folder and create four subfolders with the following names:
    • Buyer

    • Seller

    • SubmitPO

    • InvoiceToQueue

Continue to Copy files.


Copy files

In this procedure, you copy a map to the BizTalk Server repository for later use, and copy ASP files to the Web content folders of the buyer and seller.

  1. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\Tutorial\DocSpecsandMaps and copy POReqtoPO.xml.

  2. Paste the file to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\Maps\Microsoft.

  3. Use the following table to copy and paste additional files to the TutorialFiles subfolders.
    Copy from: Paste to:
    \Program Files\Microsoft BizTalk Server\Tutorial\Components\SubmitPO\Solution\SubmitNorthwindPO.asp | C:\TutorialFiles\SubmitPO
    \Program Files\Microsoft BizTalk Server\Tutorial\Components\InvoicetoQueue\Solution\DropInvoicetoMSMQ.asp | C:\TutorialFiles\InvoiceToQueue
    \Program Files\Microsoft BizTalk Server\Tutorial\Components\InvoicetoQueue\Solution\Global.asa | C:\TutorialFiles\InvoiceToQueue

Continue to Create virtual Web site directories.


Create virtual Web site directories

In this procedure, you create two virtual directories in Internet Information Services (IIS) and point them to the ASP files. The first directory simulates the seller Web site that receives purchase orders. The second directory simulates the buyer Web site that receives invoices.

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Internet Services Manager.

    The Internet Information Services Management console appears.

  4. In the Internet Information Services Management console tree, expand <your computer>, and then click Default Web Site.

  5. On the Action menu, point to New and click Virtual Directory.

    The Virtual Directory Creation Wizard opens.

  6. On the Welcome to the Virtual Directory Creation Wizard page, click Next.

  7. On the Virtual Directory Alias page, in the Alias box, type SubmitPO and click Next.

  8. On the Web Site Content Directory page, click Browse.

  9. Browse to C:\TutorialFiles\SubmitPO, click OK, and then click Next.

  10. On the Access Permissions page, click Next.

  11. Click Finish to close the Virtual Directory Creation Wizard.

  12. In the Computer Management console tree, click Default Web Site.

  13. To create the folder that simulates the buyer Web site, repeat steps 5 through 11, with the following variations:
    • In step 7, in the Alias box, type InvoiceToQueue.

    • In step 9, browse to C:\TutorialFiles\InvoiceToQueue.

    Your Computer Management console should appear similar to the following illustration.

    Computer Management console

  14. Close the Computer Management console.

Continue to Create message queues.


Create message queues

In this procedure, you create two message queues to enable the buyer system to send and receive messages. Northwind Traders uses an application to submit a purchase order request. The purchase order request is sent to the ReceivePOReq queue for further processing. When Contoso, Ltd submits an invoice through an ASP page on the buyer's Web site, the ASP page posts the invoice to the ReceiveInvoice queue for further processing.

Note

  • To complete this procedure, Message Queuing must be installed. For instructions about installing Message Queuing, see Install Message Queuing

To create the message queues:

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Computer Management.

    The Computer Management console appears.

  4. In the Computer Management console, expand Services and Applications, expand Message Queuing, and then click Private Queues.

  5. On the Action menu, point to New and click Private Queue.

    The Queue Name dialog box appears.

  6. In the Name box, type ReceivePOReq.

  7. Select the Transactional check box and click OK.

  8. To create the second message queue, repeat steps 5 through 7, with the following variation:
    • In step 6, in the Name box, type ReceiveInvoice.

    Your Computer Management console should appear similar to the following illustration.

    Computer Management console

  9. Close the Computer Management console.

Continue to Install the auxiliary components.


Install the auxiliary components

In this procedure, you install the following auxiliary components:

  • An application integration component (AIC) on the seller system that is used to generate an invoice that is based on the data in the purchase order from the buyer.

  • A Windows Script Component (WSC) on the buyer system that is used to implement a port to an XLANG schedule, and that accepts the approval or denial status for a purchase order request from the XLANG schedule.

    Important

    • If these components have been installed previously on your computer, you must first uninstall them. To uninstall the components, go to Uninstall the auxiliary components.

    International Issue

    • The BizTalk Server 2002 tutorial does not work with non-ASCII data. If you need to use non-ASCII data, change the code for the scripting component (PORequestApproval.wsc) to use the XML Document Object Model (DOM) to write data.

To install the auxiliary components:

  1. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Setup.

  2. Double-click Install_POtoInvoice.vbs.

    A message box appears, indicating that the component was successfully installed.

  3. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POReqApproval\Solution and click PORequestApproval.wsc.

  4. On the File menu, click Register.

    A message box appears, indicating that the component was successfully registered.

Continue to Module 1: Modeling Business Processes.


Uninstall the auxiliary components

Caution

  • Do not use this procedure unless you are removing a previous installation of the components.
  1. For the POtoInvoice component, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Setup on the BizTalk Server installation drive.

  2. Double-click Remove_POtoInvoice.vbs.

    A message box appears, indicating that the component was successfully uninstalled.

  3. For the Windows Script Component, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POReqApproval\Solution and click PORequestApproval.wsc.

  4. On the File menu, click Unregister.

    A message box appears, indicating that the component was successfully unregistered.

To reinstall the components, go to Install the auxiliary components.


Module 1: Modeling Business Processes

In this module, you use BizTalk Orchestration Designer to create an XLANG schedule drawing that defines and implements the automated procurement process for Northwind Traders. You then compile the XLANG schedule drawing into an executable XLANG schedule, which controls the flow of messages for the buyer system.

Objectives

  • Create an XLANG schedule drawing that defines the automated procurement process. For more information, see Creating XLANG Schedule Drawings.

  • Connect the actions in a logical sequence to further define the business processes. For more information, see Connect Shapes.

  • Implement the business processes by connecting actions to ports. For more information, see Establish the communication flow between an action and a port.

  • Add a rule to the business processes by writing a script expression. For more information, see Designing Rules.

  • Define the data flow for messages. For more information, see Communication Shapes.

  • Save the XLANG schedule drawing and compile the drawing into an XLANG schedule. For more information, see Compiling XLANG Schedules.

  • Run the XLANG schedule to process the message through BizTalk Server. For more information, see Running XLANG Schedules.

Continue to Creating the XLANG Schedule for the Buyer.

Related Topic

Designing BizTalk Orchestrations


Creating the XLANG Schedule for the Buyer

In the following procedures, you define and implement the business processes for Northwind Traders (the buyer) and create and run an XLANG schedule.

To create the XLANG schedule, continue to Create the buyer actions.

Shortcut

  • To use the existing XLANG schedule, continue to Run the XLANG schedule.


Create the buyer actions

The first step in creating this automated procurement process is to analyze the business process that Northwind Traders will use and to create an interaction diagram that describes that process. In this procedure, you use BizTalk Orchestration Designer to draw a representation of the Northwind Traders business process. Flowchart shapes are used to define the actions that take place when a purchase order request is received and when the purchase order request is either accepted or denied.

For a detailed description of the Flowchart shapes, see Flowchart Shapes. For more information about business processes, see Understanding Business Processes.

To create the buyer actions:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Orchestration Designer.

  2. Drag the Action shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position the shape below the Begin shape.

  3. Right-click the Action shape and click Properties.

    The Action Properties dialog box appears.

  4. In the Name box, type Receive PO Request and click OK.

    Caution

    • For this scenario to run correctly, you must type all names exactly as indicated. The tutorial components use these names.
  5. Drag the Decision shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position this shape below the Receive PO Request action.

  6. Right-click the Decision shape and click Add Rule.

    The Rule Properties dialog box appears.

  7. In the Rule name box, type Denied and click OK.

    Entering information in the Rule description box is optional.

    Leave the Script expression box empty. Later in this module, you add a script expression that implements the decision rule, after you bind the Decision shape to the script component, which provides the message and field names.

  8. Repeat steps 2 through 4 to create the following three actions:
    • Position a second Action shape to the right of the Decision shape. Name this action Send Denial.

    • Position a third Action shape below the Decision shape. Name this action Send Approval.

    • Position a fourth Action shape below the Send Approval action. Name this action Write PO Request to File.
  9. Drag the End shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position the shape below the Send Denial action.

    If the purchase order request is not approved, the XLANG schedule displays a denial message and ends.

  10. Drag the End shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position the shape below the Write PO Request to File action.

    If the purchase order request is approved, the XLANG schedule writes the purchase order request to a file directory, displays an approval message, and then ends.

Continue to Connect the buyer actions in a sequence.


Connect the buyer actions in a sequence

After you have created Northwind Traders actions, you need to further define the sequence of events by connecting the Flowchart shapes so that the business process begins when a purchase order request is received and ends when the purchase order request is either accepted or denied. You then save the representation as an XLANG schedule drawing with the file extension .skv. For more information, see Connect Shapes.

To connect the buyer actions:

  1. Click the Begin shape to highlight the control handles.

    Highlighted Begin shape

    Drag the bottom control handle to the top connection point of the Receive PO Request action.

    The Receive PO Request action represents the start of the business process. When a purchase order request is received, the XLANG schedule starts running.

    Notes

    • A yellow diamond on a highlighted shape indicates a control handle. You can drag control handles to connect to an action.

    • A blue X on a shape indicates a connection point.

    • Connection points on the side of an Action shape are used only to connect to ports, not to other Action shapes.
  2. Repeat step 1 to create a connection for the following action:
    • Connect the Receive PO Request action to the Decision shape.
  3. Select the Denied rule in the Decision shape and drag the right control handle of the Denied rule to the top connection point of the Send Denial action.

  4. Select the Else rule in the Decision shape and drag the left control handle of the Else rule to the top connection point of the Send Approval action.

    Note

    • You can connect the rules in the Decision shape to the Send Approval and Send Denial actions from either the right or left control handle.
  5. Connect the Send Approval action to the Write PO Request to File action.

  6. Connect the Write PO Request to File action to the End shape positioned below it.

  7. Connect the Send Denial action to the End shape positioned below it.

  8. On the File menu, click Save As.

    The Save XLANG Schedule Drawing As dialog box appears.

    Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab on the BizTalk Server installation drive.

  9. In the File name box, type Buyer1 and click Save.

The XLANG schedule drawing that you created and saved should appear similar to the following illustration.

XLANG schedule drawing

Continue to Implement a port by using Message Queuing to receive a purchase order request.


Implement a port by using Message Queuing to receive a purchase order request

In the preliminary setup for this tutorial you created the ReceivePOReq message queue. In this procedure, you add the Messaging Queuing shape to the XLANG drawing and implement a port to the ReceivePOReq message queue.

The Message Queuing shape represents the Message Queuing Service that is used to send or receive messages. The service is configured to monitor the ReceivePOReq message queue for a purchase order request. After the purchase order request is in the queue, the XLANG schedule begins processing. For more information, see Using the Message Queuing Shape.

For information about the use of ports and messaging ports, see Integrating BizTalk Services.

To implement the port:

  1. Drag the Message Queuing shape from the Implementation stencil in the rightmost column to the Business Process page.

    Position the Message Queuing shape so that it is horizontally aligned with the Receive PO Request action.

    The Message Queuing Binding Wizard opens.

  2. On the Welcome to the Message Queuing Binding Wizard page, verify that Create a new port is selected.

  3. In the Create a new port box, type ReceivePORequest and click Next.

  4. On the Static or Dynamic Queue Information page, verify that Static queue is selected and click Next.

  5. On the Queue Information page, click Use a known queue for all instances.

  6. In the Enter the queue name box, type .\private$\ReceivePOReq and click Next.

  7. On the Advanced Port Properties page, click Finish.

    On the Business Process page, the ReceivePORequest port and the associated Message Queuing implementation appear.

Note

  • A static queue is used instead of a dynamic queue because we know exactly where we want the PO request delivered and have already created a queue specifically to receive it.

Continue to Create the communication flow for the Receive PO Request action.


Create the communication flow for the Receive PO Request action

In this procedure, you use the XML Communication Wizard to facilitate communication between the Action shape Receive PO Request and the ReceivePORequest port. Through the XML Communication Wizard, you provide specific information and specifications that the XLANG Scheduler Engine will use to identify and retrieve the correct message from the queue. In addition, you add the message field POTtl that will be used to enable data-sensitive routing.

  1. Select the Receive PO Request action and drag the control handle on the right of the Receive PO Request action to the left connection point of the ReceivePORequest port.

    The XML Communication Wizard opens.

  2. On the Welcome to the XML Communication Wizard page, click Receive and click Next.

  3. On the Message Information page, verify that Create a new message is selected.

  4. In the Message name box, type POReq and click Next.

  5. On the XML Translation Information page, verify that Receive XML messages from the queue is selected and click Next.

  6. On the Message Type Information page, in the Message type box, type POReq and click Next.

  7. On the Message Specification Information page, click Browse.

    The Browse for Specification dialog box appears.

  8. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\DocSpecsandMaps on the BizTalk Server installation drive.

  9. Click POReq.xml and click Open.

  10. Click Add.

    The Field Selection dialog box appears.

  11. In the Select node area, expand Total, click POTtl, and then click OK.

    In the Message fields area, POTtl should appear in the list of message fields.

  12. Click Finish.

After you implement the port and create the communication flow, the XLANG schedule drawing should appear similar to the following illustration.

XLANG schedule drawing

Continue to Implement a port by using a script component.


Implement a port by using a script component

For this procedure, you use the Windows Script Component (WSC), PORequestApproval.wsc, that you installed and registered in the preliminary setup of this tutorial. This script component enables certain actions to be performed within the XLANG schedule. In this procedure, you implement the ApprovalComponent port so that approval and denial actions can be connected to the port and bound to the script component. For more information, see Using the Script Component Shape.

The script component enables the following actions to be performed within the XLANG schedule.

If the total of the purchase order request exceeds $1,000:

  • The Decision shape sends a denial message to the port.

  • The script component displays a message box that notifies the user of the denial.

  • The XLANG schedule ends.

If the total of the purchase order request is $1,000 or less:

  • The Decision shape sends an approval message to the port.

  • The script component displays a message box that notifies the user of the approval.

  • The script component writes the purchase order request message to a local file directory.

  • The XLANG schedule ends.

To implement the port:

  1. Drag the Script Component shape from the Implementation stencil in the rightmost column to the Business Process page.

    Position the shape so that it is horizontally aligned with the Decision shape.

    The Script Component Binding Wizard opens.

  2. On the Welcome to the Script Component Binding Wizard page, in the Create a new port box, type ApprovalComponent and click Next.

  3. On the Static or Dynamic Communication page, verify that Static is selected and click Next.

  4. On the Specify the Script File page, click Browse.

  5. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POReqApproval\Solution on the BizTalk Server installation drive.

  6. Click PORequestApproval.wsc, click Open, and then click Next.

  7. On the Component Instantiation Information page, verify that Use the Prog ID "BTSTutorial.PORequestApproval" is selected and click Next.

  8. On the Method Information page, click Check All and click Next.

  9. On the Advanced Port Properties page, click Finish.

Continue to Define message properties for the script component.


Define message properties for the script component

In this procedure, you use the Method Communication Wizard to define the flow of messages from the Action shapes to the script component. For a detailed description of each step in this process, see Send or receive synchronous messages.

  1. Select the Send Denial action and drag the control handle on the right to the ApprovalComponent Windows Script Component port.

    The Method Communication Wizard opens.

  2. On the Welcome to the Method Communication Wizard page, verify that Initiate a synchronous method call is selected and click Next.

  3. On the Message Information page, verify that Create a new message is selected and click Next.

  4. On the Message Specification Information page, in the Methods list, click SendDenial and click Finish.

  5. Select the Send Approval action and drag the control handle on the right of the Send Approval action to the ApprovalComponent port.

    The Method Communication Wizard opens.

  6. On the Welcome to the Method Communication Wizard page, verify that Initiate a synchronous method call is selected and click Next.

  7. On the Message Information page, verify that Create a new message is selected and click Next.

  8. On the Message Specification Information page, in the Methods list, click SendApproval and click Finish.

  9. Select the Write PO Request to File action and drag the control handle on the right of the Write PO Request to File action to the ApprovalComponent port.

    The Method Communication Wizard opens.

  10. On the Welcome to the Method Communication Wizard page, verify that Initiate a synchronous method call is selected and click Next.

  11. On the Message Information page, verify that Create a new message is selected and click Next.

  12. On the Message Specification Information page, in the Methods list, verify that WriteToFile is selected and click Finish.

Continue to Write the script expression for the decision rule.


Write the script expression for the decision rule

The Northwind Traders business rules dictate that a purchase order request is denied if it is greater than $1,000. The message needs to be routed according to this business rule. The XLANG schedule passes the value in the total field, POTtl, of the purchase order request to the Decision shape. The scripting expression in the decision rule branches the path of the schedule and sends the appropriate message to the port implementation that uses the Windows Script Component (WSC). The denial decision rule contains the script expression that defines the behavior of the Decision shape. The scripting expression evaluates to either TRUE or FALSE and also defines the logic and variable names that are used by the Decision shape.

To write the script expression:

  1. Click the Data tab at the bottom of the page.

    The Data page appears.

  2. View the POReq message to find the field name.

    To write the script expression, both the message name and the field name are required. In this case, the message name is POReq and the field name is POTtl.

  3. Click the Business Process tab at the bottom of the page.

    The Business Process page appears.

  4. Right-click the Decision shape and click Properties.

    The Decision Properties dialog box appears.

  5. Verify that Denied is selected and click Edit.

    The Rule Properties dialog box appears.

  6. In the Script expression box, type POReq.POTtl > 1000.

    This indicates that if the total field in the purchase order request is greater than $1000, the request is denied.

  7. Click OK to close the Rule Properties dialog box, and click OK to close the Decision Properties dialog box.

The XLANG schedule drawing should appear similar to the following illustration.

XLANG schedule drawing

Continue to Define the data flow.


Define the data flow

To define data flow within the business process, you create connections between fields in Message shapes on the Data page. The connections indicate that the data contained in the document field in POReq, will be passed on to the document fields in the SendDenial, SendApproval, and WriteToFile messages. The flow of data between messages must be defined before you can compile the XLANG schedule. For a detailed description of the data page, see The Data Page.

To define the data flow:

  1. Click the Data tab at the bottom of the page.

    The Data page appears.

  2. In the POReq message, click the Document field and drag the control handle on the right to a connection point on the Document field in the SendDenial_in message.

  3. Repeat step 2 by clicking the Document field and dragging the highlighted control handle on the right from the POReq box to a connection point on the following fields:
    • The Document field in the SendApproval_in box.

    • The Document field in the WriteToFile_in box.

Note

  • Click the Document field of the POReq message before trying to drag the control handle to the other fields.

The completed Data page should appear similar to the following illustration.

Continue to Save the XLANG schedule drawing.


Save the XLANG schedule drawing

  • On the File menu, click Save Buyer1.skv.

Continue to Compile the XLANG schedule.


Compile the XLANG schedule

In this procedure, you compile the XLANG schedule drawing into an XLANG schedule that will be activated when the purchase order request is received. When you compile an XLANG schedule drawing, any problems within the drawing will be identified. For more information about compiling an XLANG schedule drawing into an executable XLANG schedule, see Compiling XLANG Schedules.

  1. On the File menu, click Make XLANG Buyer1.skx.

    The Save XLANG Schedule to dialog box appears.

  2. Verify that the XLANG schedule will be saved to the \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab folder on the BizTalk Server installation drive and click Save.

  3. On the File menu, click Exit to close BizTalk Orchestration Designer.

Continue to Run the XLANG schedule.


Run the XLANG schedule

In this procedure, you run an application that drops a purchase order request to the ReceivePOReq queue and activates the XLANG schedule. You run the application twice to view the business process created in Module 1. The first time the purchase order request is approved, a message will be sent and the purchase order request will be written to a file. The second time the application is run, the purchase order will be denied, a message will be sent, and the process will stop.

To run the XLANG schedule:

  1. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive.

  2. Double-click ExecuteTutorial.exe.

    This application is used to activate the XLANG schedule by means of a moniker.

    The ExecuteTutorial application opens.

  3. Click Browse for Schedule.

    Shortcut

    • If BizTalk Server and all its components are installed on the C drive you can use the existing XLANG schedule. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution and continue to step 5.
  4. If you created the Buyer1 XLANG schedule, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab.

  5. Click the Buyer1.skx XLANG schedule file and click Open.

  6. Click Browse for Data File and browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\SampleData.

  7. Click POReqAccept.xml and click Open.

  8. Click Start XLANG Schedule.

    Because its total is less than $1000, the purchase order request is approved. A message box appears, notifying you that the application passed data to the XLANG Scheduler Engine. At this point, the application is finished. A second message box notifies you that the purchase order request has been approved. Click OK to close the message boxes.

  9. Click End to close the ExecuteTutorial application.

    Important

    • If you see an Automation error when running this application, check to make sure that you have properly configured the private queue and that its name is correct.
  10. Browse to C:\TutorialFiles\Buyer.

    The file name is POReqXXXXX.xml, where XXXXX represents a unique set of numbers. Double-click the file to open it in Microsoft Internet Explorer. This is a copy of the purchase order request file that the application posted to the message queue. After viewing this file, delete it.

  11. Repeat steps 1 through 5 to run the ExecuteTutorial application again.

  12. Click Browse for Data File and browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\SampleData.

  13. Click POReqDeny.xml and click Open.

  14. Click Start XLANG Schedule.

    Because its total exceeds $1000, the purchase order request is denied. A message box appears, notifying you that the application is finished. A second message box notifies you that the document denial has been received. Click OK to close the message boxes.

  15. Click End to close the ExecuteTutorial application.

The following illustration shows the flow of data when you run the XLANG schedule.

Flow of data

Continue to Module 1 Summary.


Module 1 Summary

In this module, you accomplished the following:

  • Created the XLANG schedule drawing that described the automated procurement process. For more information, see Creating XLANG Schedule Drawings.

  • Connected the actions in a logical sequence that described the business process. For more information, see Connect Shapes.

  • Implemented the business process by connecting actions to ports. For more information, see Establish the communication flow between an action and a port.

  • Added a rule to the business process by writing a script expression. For more information, see Designing Rules.

  • Defined the data flow for messages. For more information, see Communication Shapes.

  • Saved the XLANG schedule drawing and compiled the drawing into the XLANG schedule. For more information, see Compiling XLANG Schedules.

  • Ran the XLANG schedule twice to process the purchase order request through BizTalk Server, observing the approval and denial actions. For more information, see Running XLANG Schedules.

The highlighted areas of the following illustration show the steps you completed in this module.

Continue to Module 2: Creating Specifications and Maps.

Related Topic

Designing BizTalk Orchestrations


Module 2: Creating Specifications and Maps

Now that you have designed the business process and know how the flow of communication will work within this model, you need to define the structure of the business documents that will be sent and received. The structure of the business documents is defined in XML schemas, also referred to as specifications. In this module, you use BizTalk Editor to create payment specifications and purchase order specifications for the buyer, Northwind Traders.

Contoso, Ltd uses a common schema for the invoice they send to Northwind Traders. When Northwind Traders receives the invoice, the specifications need to be converted to payment specifications. You use BizTalk Mapper to create a map between the records and fields of the payment specifications that you create for Northwind Traders and the CommonInvoice specifications that Contoso, Ltd uses.

Objectives

  • Create a specification. For more information, see Using BizTalk Editor.

  • Add new records and fields to a specification. For more information, see Add new fields to records.

  • Create a map. For more information, see Using BizTalk Mapper.

  • Create links between fields in a map. For more information, see Creating Links.

  • Use functoids to mathematically manipulate values in a map. For more information, see Understanding Functoids.

  • Save specifications and maps to the Web Distributed Authoring and Versioning (WebDAV) repository. For more information, see Store specifications and Store maps.

Continue to Using BizTalk Editor.

Related Topic

Creating Specifications and Mapping Data


Using BizTalk Editor

You use BizTalk Editor to create, edit, and manage specifications.

To use BizTalk Editor to create the payment specification, continue to Create the payment specification.

Shortcut

  • To use the existing payment specification, continue to Use the existing payment specification.


Use the existing payment specification

  1. Copy PaymentSpec.xml from \Program Files\Microsoft BizTalk Server\Tutorial\DocSpecsandMaps on the BizTalk Server installation drive.

  2. Paste the file to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

To use BizTalk Editor to create the purchase order request specification, continue to Create the purchase order request specification.

Shortcut

  • If BizTalk Server and all its components are installed on the C drive you can use the existing purchase order request specification. Continue to Use the existing purchase order request specification.


Create the payment specification

In this procedure, you create an XML schema, or payment specifications, that define the structure and data that Northwind Traders will use when sending a payment to Contoso, Ltd. For more information about specifications, see Understanding Specifications.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

  2. On the File menu, click New.

    The New Document Specification dialog box appears.

  3. Click the Blank Specification icon and click OK.

  4. In the root node, click BlankSpecification.

  5. On the Declaration tab, double-click the Value field in the Name row, type Payment, and then press ENTER.

  6. Double-click the Value field in the Model row, click Open, and then press ENTER.

Continue to Add new records to the Payment root node of the payment specification.


Add new records to the Payment root node of the payment specification

  1. Right-click the Payment root node and click New Record.

  2. Name this record PaymentHeader and press ENTER.

  3. Follow steps 1 and 2 to create and name four additional records under the Payment root node.

    These records are all child records of the Payment root node. Name the records as follows:

    • Seller

    • Buyer

    • Item

    • PaymentSummary

Continue to Add new records to existing records in the payment specification.


Add new records to existing records in the payment specification

  1. Right-click the Seller record and click New Record.

  2. Name this record Address and press ENTER.

  3. Follow steps 1 and 2 to create child records for the parent records listed in the following table.
    Parent record | Child record name
    Seller | ContactInfo
    Buyer | Address
    Buyer | ContactInfo

Continue to Add new fields to existing records in the payment specification.


Add new fields to existing records in the payment specification

  1. Right-click the PaymentHeader record and click New Field.

  2. Name this field PONumber and press ENTER.

  3. On the Declaration tab, double-click the Value field in the Data Type row, click String, and then press ENTER.

  4. On the Declaration tab, double-click the Value field in the Minimum Length row, type 1, and then press ENTER.

  5. On the Declaration tab, double-click the Value field in the Maximum Length row, type 22, and then press ENTER.

  6. Follow steps 1 through 5 to create fields for the records or child records listed in the following table.

    Each record contains multiple fields.

    You do not have to create the fields for the buyer because parallel record names exist for the buyer and the seller. All records with the same name contain the same record and field information. When you add fields to the Seller/Address or Seller/ContactInfo record, the Buyer/Address or Buyer/ContactInfo record is automatically updated with the same fields.

    Parent record | Field name | Data type | Minimum length | Maximum length
    PaymentHeader | Date | Date | Not applicable | Not applicable
    Seller/Address | Name | String | 1 | 60
    Address1 | String | 1 | 55
    Address2 | String | 1 | 55
    City | String | 2 | 30
    State | String | 2 | 2
    Zip | String | 3 | 15
    Country | String | 2 | 3
    Seller/ContactInfo | Name | String | 1 | 60
    Number | String | 1 | 60
    Item | Quantity | Real(r4) | Not applicable | Not applicable
    Price | Real(r4) | Not applicable | Not applicable
    Description | String | 1 | 80
    ExtendedPrice | Real(r4) | Not applicable | Not applicable
    PaymentSummary | Total | Real(r4) | Not applicable | Not applicable

Continue to Store the payment specification to WebDAV.


Store the payment specification to WebDAV

When you store a file to WebDAV, it is stored on the server rather than on the local drive. WebDAV locks documents to prevent users from accidentally overwriting each others' changes. It also enables users to share and work with server-based documents, regardless of their authoring tools, platforms, or the type of Web servers on which the files are stored. In the following procedure you also validate the document instance. If the document instance is not valid the Warning tab indicates this and displays errors that indicate why.

  1. On the File menu, click Store to WebDAV.

    The Store to WebDAV dialog box appears.

  2. Double-click the Microsoft folder.

  3. In the File name box, type PaymentSpec and click Save.

  4. On the Tools menu, click Validate Instance.

    The Validate Document Instance dialog box appears.

  5. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive.

  6. Click payment_valid.xml and click Open.

    Warnings or errors, if any, appear on the Warnings tab. To resolve an error, select the warning message.

The payment specification should appear similar to the following illustration.

To use BizTalk Editor to create the purchase order request specification, continue to Create the purchase order request specification.

Shortcut

  • If BizTalk Server and all its components are installed on the C drive you can use the existing purchase order request specification. Continue to Use the existing purchase order request specification.


Use the existing purchase order request specification

  1. Copy POReq.xml from \Program Files\Microsoft BizTalk Server\Tutorial\DocSpecsandMaps on the BizTalk Server installation drive.

  2. Paste the file to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

Continue to Using BizTalk Mapper.


Create the purchase order request specification

In this procedure, you create the root node of the purchase order request specification. The purchase order request specification defines the structure and data that Northwind Traders will use when submitting a purchase order request for approval.

To create the root node:

  1. On the File menu, click New.

    The New Document Specification dialog box appears.

  2. Click the Blank Specification icon and click OK.

  3. In the root node, click BlankSpecification.

  4. On the Declaration tab, double-click the Value field in the Name row, type POReq, and then press ENTER.

  5. Double-click the Value field in the Model row, click Open, and then press ENTER.

Continue to Add new records to the root node in the purchase order request specification.


Add new records to the root node in the purchase order request specification

  1. Right-click the POReq root node and click New Record.

  2. Name this record Header and press ENTER.

  3. Follow steps 1 and 2 to create and name five additional records under the POReq root node.

    These records are all child records of the POReq root node. Name the records as follows:

    • EmployeeInfo

    • BillTo

    • ShipTo

    • Item

    • Total

Continue to Add new records to existing records in the purchase order request specification.


Add new records to existing records in the purchase order request specification

  1. Right-click the BillTo record and click New Record.

  2. Name this record Address and press ENTER.

  3. Follow steps 1 and 2 to create and name a child record Address for the parent record called ShipTo.

Continue to Add new fields to existing records in the purchase order request specification.


Add new fields to existing records in the purchase order request specification

  1. Right-click the Header record and click New Field.

  2. Name this field Date and press ENTER.

  3. On the Declaration tab, double-click the Value field in the Data Type row, click Date, and then press ENTER.

  4. Right-click the EmployeeInfo record and click New Field.

  5. Name this field EmpID and press ENTER.

  6. On the Declaration tab, double-click the Value field in the Data Type row, click String, and then press ENTER.

  7. On the Declaration tab, double-click the Value field in the Minimum Length row, type 1, and then press ENTER.

  8. On the Declaration tab, double-click the Value field in the Maximum Length row, type 60, and then press ENTER.

  9. Follow steps 4 through 8 to create fields for the records or child records listed in the following table.

    Each record contains multiple fields.

    You do not have to create the fields for ShipTo because parallel record names exist for BillTo and ShipTo. All records with the same name contain the same record and field information. When you add fields to the BillTo/Address record, the ShipTo/Address record is automatically updated with the same fields.

    Parent record | Field name | Data type | Minimum length | Maximum length
    EmployeeInfo | LastName | String | 1 | 30
    FirstName | String | 1 | 30
    BillTo/Address | Name | String | 1 | 60
    Address1 | String | 1 | 55
    Address2 | String | 1 | 55
    City | String | 2 | 30
    State | String | 2 | 2
    Zip | String | 3 | 15
    Country | String | 2 | 3
    Item | Quantity | Real(r4) | Not applicable | Not applicable
    Price | Real(r4) | Not applicable | Not applicable
    Description | String | 1 | 80
    UnitofMeasure | String | 2 | 2
    ExtendedPrice | Real(r4) | Not applicable | Not applicable
    Total | LineItemTtl | Real(r4) | Not applicable | Not applicable
    QtyTtl | Real(r4) | Not applicable | Not applicable
    POTtl | Real(r4) | Not applicable | Not applicable

Continue to Save the purchase order request specification.


Save the purchase order request specification

As in the previous Store the payment specification to WebDAV procedure, you want to store the file to WebDAV rather than to the local drive.

  1. On the File menu, click Store to WebDAV.

    The Store to WebDAV dialog box appears.

  2. Verify that the Microsoft folder is open.

  3. In the File name box, type POReq and click Save.

  4. On the Tools menu, click Validate Instance.

    The Validate Document Instance dialog box appears.

  5. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\SampleData on the BizTalk Server installation drive.

  6. Click POReqAccept.xml and click Open.

    Warnings or errors, if any, appear on the Warnings tab.

    The purchase order request specification should appear similar to the following illustration.

  7. On the File menu, click Exit to close BizTalk Editor.

Continue to Using BizTalk Mapper.


Using BizTalk Mapper

In this procedure, you use BizTalk Mapper to create a map that transforms the data from a message that conforms to the CommonInvoice specifications that Contoso, Ltd uses, into data in a message that conforms to the PaymentSpec specifications that you created for the buyer, Northwind Traders.

In the next module, you will see how BizTalk Messaging Services uses this map within a channel to specify how data in a document using one XML schema is transformed into a document that uses a different XML schema.

If you printed the overview illustration provided at the beginning of this tutorial, you might want to review the visual representation of this process as depicted in the lower section of the drawing under "BizTalk Messaging Services."

To use BizTalk Mapper to create the map, continue to Create the InvoiceToPayment map.

Shortcut

  • If BizTalk Server and all its components are installed on the C drive you can use the existing map. Continue to Use existing InvoiceToPayment map.


Use existing InvoiceToPayment map

  1. Copy InvoiceToPayment.xml from \Program Files\Microsoft BizTalk Server\Tutorial\DocSpecsandMaps on the BizTalk Server installation drive.

  2. Paste the file to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\Maps\Microsoft.

Continue to Module 3: Configuring BizTalk Messaging Services.


Create the InvoiceToPayment map

Before you create the map, you need to open CommonInvoice.xml, which will be the source specification and PaymentSpec.xml, which will be the destination specification.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Mapper.

  2. On the File menu, click New.

    The Select Source Specification Type dialog box appears.

  3. Click the WebDAV Files icon and click OK.

    The Retrieve Source Specification dialog box appears.

  4. Double-click the Microsoft folder.

  5. Click CommonInvoice.xml and click Open.

    The Select Destination Specification Type dialog box appears.

  6. Click the WebDAV Files icon and click OK.

  7. Click PaymentSpec.xml and click Open.

Continue to Create links between fields.


Create links between fields

In the following procedure, you link fields from the source specification to fields in the destination specification. Links perform the basic function of copying data from the Source Specification tree records and fields to the Destination Specification tree records and fields.

To create links between fields:

  1. In the Source Specification tree, expand the InvoiceHeader record to display the associated fields.

    For more information, see Expand tree items.

  2. In the Destination Specification tree, expand the PaymentHeader record to display the associated fields.

  3. Drag the InvoiceHeader/Date field from the Source Specification tree to the PaymentHeader/Date field in the Destination Specification tree.

  4. Follow steps 1 through 3 to create links between the fields listed in the following tables.
    Source record/field | Destination record/field
    InvoiceHeader/Number | PaymentHeader/PONumber

    Seller/Address/Name | Seller/Address/Name
    Seller/Address/Address1 | Seller/Address/Address1
    Seller/Address/Address2 | Seller/Address/Address2
    Seller/Address/City | Seller/Address/City
    Seller/Address/State | Seller/Address/State
    Seller/Address/PostalCode | Seller/Address/Zip
    Seller/Address/Country | Seller/Address/Country

    Seller/ContactInfo/ContactName | Seller/ContactInfo/Name
    Seller/ContactInfo/ContactNumber | Seller/ContactInfo/Number

    Buyer/Address/Name | Buyer/Address/Name
    Buyer/Address/Address1 | Buyer/Address/Address1
    Buyer/Address/Address2 | Buyer/Address/Address2
    Buyer/Address/City | Buyer/Address/City
    Buyer/Address/State | Buyer/Address/State
    Buyer/Address/PostalCode | Buyer/Address/Zip
    Buyer/Address/Country | Buyer/Address/Country

    Buyer/ContactInfo/ContactName | Buyer/ContactInfo/Name
    Buyer/ContactInfo/ContactNumber | Buyer/ContactInfo/Number

    Item/ItemHeader/Quantity | Item/Quantity
    Item/ItemHeader/Price | Item/Price
    Item/ItemDescription/Description | Item/Description

    InvoiceSummary/InvoiceTotal/Amount PaymentSummary/Total

Continue to Use functoids to create links.


Use functoids to create links

In this procedure, you use a functoid to multiply the Quantity field by the Price field in the source specification, and place this value in the ExtendedPrice field in the destination specification.

To use functoids to create links:

  1. On the View menu, click Functoid Palette.

    The Functoid Palette appears.

  2. Click the Mathematical tab, drag the Multiplication functoid Multiplication functoid to the mapping grid, and then close the Functoid Palette.

  3. In the Source Specification tree, drag the Item/ItemHeader/Quantity field to the functoid.

  4. In the Source Specification tree, drag the Item/ItemHeader/Price field to the functoid.

  5. Drag the Multiplication functoid to the Item/ExtendedPrice field in the Destination Specification tree.

Continue to Compile the map.


Compile the map

It is necessary to compile a map before you use it so you can resolve any warnings or errors.

  1. On the Tools menu, click Compile Map.

  2. In the lower pane, click the Output tab.

    The information on the Output tab indicates that an XSL map has been created. Warnings or errors, if any, appear on the Warnings tab.

Continue to Store the map to WebDAV.


Store the map to WebDAV

  1. On the File menu, click Store to WebDAV.

    The Store to WebDAV dialog box appears.

  2. Double-click the Microsoft folder.

  3. In the File name box, type InvoiceToPayment and click Save.

    The map you create should appear similar to the following illustration.

  4. On the File menu, click Exit to close BizTalk Mapper.

Continue to Module 2 Summary.


Module 2 Summary

In this module, you accomplished the following:

  • Created a specification. For more information, see Understanding Specifications.

  • Added new records and fields to a specification. For more information, see Add new fields to records.

  • Created a map. For more information, see Using BizTalk Mapper.

  • Created links between fields in a map. For more information, see Creating Links.

  • Used functoids to mathematically manipulate values in a map. For more information, see Understanding Functoids.

  • Saved specifications and maps to the WebDAV repository. For more information, see Store specifications and Store maps.

The highlighted areas of the following illustration show the steps you completed in this module.

Continue to Module 3: Configuring BizTalk Messaging Services.

Related Topic

Creating Specifications and Mapping Data


Module 3: Configuring BizTalk Messaging Services

At this point in the tutorial, you have designed the business process and the communication flow, and defined the structure of the documents that will be sent and received. The next step is to configure BizTalk Messaging Services on the buyer and seller systems so that the documents can be sent and received.

In this module, you learn how to use BizTalk Messaging Manager to configure organizations, channels, and messaging ports for the seller and buyer systems. You also learn how to use BizTalk Server Administration to configure a File receive function.

Objectives

  • Create document definitions. For more information, see Create and Manage Document Definitions.

  • Create organizations. For more information, see Create and Manage Organizations.

  • Create messaging ports. For more information, see Create and Manage Messaging Ports and Integrating BizTalk Services.

  • Create channels. For more information, see Create and Manage Channels.

  • Use a map in a channel to transform a document. For more information, see Using BizTalk Mapper.

  • Create a receive function. For more information, see Receive Functions.

Continue to Configuring the Buyer System.

Related Topic

Using BizTalk Messaging Manager


Configuring the Buyer System

You use BizTalk Messaging Manager to create organizations that represent trading partners.

To use BizTalk Messaging Manager to configure the Northwind Traders system, continue to Create the organizations for the buyer system.

Shortcut

  • If BizTalk Server and all its components are installed on the C drive you can use a script to configure the Northwind Traders system. Continue to Configure the buyer system using a configuration script.


Configure the buyer system using a configuration script

This script configures the following:

  • A source organization named Northwind Traders on Buyer on the buyer system.

  • A destination organization named Contoso on Buyer on the buyer system.

  • Four document definitions that reference specifications for CommonPO, CommonInvoice, PaymentSpec, and POReq.

  • A messaging port and channel that define the movement of a purchase order request from the buyer system to the seller system by using an HTTP transport service to an ASP file on the seller system.

  • A messaging port and channel that define the movement of an invoice that has been delivered to the buyer and transformed into a payment document on the seller system.

Caution

  • If you used BizTalk Messaging Manager and BizTalk Server Administration to configure the buyer system, do not run the configuration script.

To run the script that configures BizTalk Messaging Services for the buyer system:

  1. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Setup\MessagingConfigurationScript on the BizTalk Server installation drive.

  2. Double-click ConfigureBuyer.VBS.

    A message box appears, indicating success.

Continue to Configuring the Seller System.


Create the organizations for the buyer system

BizTalk Messaging Manager is used to manage the exchange of documents by configuring BizTalk Messaging Services. You must use BizTalk Messaging Manager to configure BizTalk Messaging Services prior to processing documents. The organizations that you create serve as the source for a channel or the destination for a messaging port. The messaging port and channel define the movement of documents between trading partners. For more information, see Understanding Organizations.

In this procedure, you create the source organization, Northwind Traders, and the destination organization, Contoso, Ltd, on Northwind Traders system.

Important

  • If you used the configuration script, do not use BizTalk Messaging Manager and BizTalk Server Administration to configure the buyer system. Continue to Configuring the Seller System.

To create the organizations on the Northwind Traders system:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. On the File menu, point to New and click Organization.

    The New Organization dialog box appears.

  4. In the Organization name box, type Contoso on Buyer and click OK.

  5. Repeat steps 3 and 4, naming the new organization Northwind Traders on Buyer.

Continue to Create the document definitions for the buyer and seller systems.


Create the document definitions for the buyer and seller systems

In this procedure, you create four document definitions that reference the document specifications, CommonInvoice, CommonPO, PaymentSpec, and POReq. The buyer and the seller systems share these document definitions so that both systems understand the business document that is being transfered between the systems. A document definition represents the type of inbound or outbound document in a channel and provides a pointer to the appropriate specification. For more information, see Understanding Document Definitions.

To create the document definitions:

  1. On the File menu, point to New and click Document Definition.

    The New Document Definition dialog box appears.

  2. In the Document definition name box, type Purchase Order.

  3. Select the Document specification check box and click Browse.

    The Select a Document Specification from the WebDAV Repository dialog box appears.

  4. Double-click the Microsoft folder.

  5. Click CommonPO.xml and click Open.

  6. Click OK to close the New Document Definition dialog box.

  7. Repeat steps 1 through 6 to create new document definitions with the following variations:
Document definition name | Document specification
Invoice | CommonInvoice.xml
Purchase Order Request | POReq.xml
Payment | PaymentSpec.xml

Continue to Create a messaging port to Contoso, Ltd for the buyer system.


Create a messaging port to Contoso, Ltd for the buyer system

In this procedure, you create a messaging port for the buyer system. A messaging port defines the destination for a document.

In this scenario, when a purchase order request is accepted, Biztalk Messaging Services locates the appropriate channel to process it. After the channel processes the document, it points the server to its associated messaging port, which directs the server through the sequence of steps necessary to transport the document to the specified destination organization. The messaging port that you create in this procedure has as its destination organization "Contoso on Buyer." You create the channel after you create the messaging port.

The transport properties that you specify for a messaging port determine the transport service used to convey documents to the destination organization and the specific address to which the documents are sent. For this messaging port, you specify the HTTP transport service to deliver documents to an ASP file on Contoso's Web site.

To create the messaging port:

  1. On the File menu, point to New, point to Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. In the Name box, type Port to Contoso via HTTP and click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  4. Click Contoso on Buyer and click OK.

  5. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  6. In the Transport type list, click HTTP.

  7. In the Address box, after the http:// prefix, type the name of your computer followed by /SubmitPO/SubmitNorthwindPO.asp, click OK, and then click Next.

    For example, if this message is being delivered to an ASP page on Contoso's Web site you might type, http://ContosoLtd/SubmitPO/SubmitNorthwindPO.asp.

    To find the name of your computer, complete the following steps:

    1. On the Start menu, point to Settings and click Control Panel.

    2. Double-click Administrative Tools.

    3. Double-click Computer Management.

      The Computer Management console appears.

    4. On the Action menu, click Properties.

      The Computer Management (Local) Properties dialog box appears.

    5. Click the Network Identification tab.

      The name of your computer appears in the Computer name field.

  8. On the Envelope Information page, click Next.

  9. On the Security Information page, verify that the Create a channel for this messaging port check box is selected.

  10. In the Channel type list, click From an organization and click Finish.

    The New Channel Wizard opens.

Continue to Create a channel from Northwind Traders for the buyer system.


Create a channel from Northwind Traders for the buyer system

After you create the messaging port, you need to define the channel that is associated with this messaging port. In this channel, we identify the source of the document as "Northwind Traders on Buyer," and specify that the document that is coming in is a purchase order request, and that the outbound document will be a purchase order. We will use the POReqtoPO.xml map to transform the document from a PO request to a PO. For more information, see Understanding Channels.

If you printed the overview illustration provided at the beginning of this tutorial, you might want to review the visual representation of the channel and messaging port created in these procedures.

To create the channel:

  1. On the General Information page, in the Name box, type Channel for POReq to PO and click Next.

  2. On the Source Organization page, click Browse.

    The Select an Organization dialog box appears.

  3. Click Northwind Traders on Buyer, click OK, and then click Next.

  4. On the Inbound Document page, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  5. Click Purchase Order Request, click OK, and then click Next.

  6. On the Outbound Document page, to the right of the Outbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  7. Click Purchase Order and click OK.

  8. Verify that the Map inbound document to outbound document check box is selected.

  9. To the right of the Map reference box, click Browse.

    The Select a Map from the WebDAV Repository dialog box appears.

  10. Double-click the Microsoft folder.

  11. Click POReqtoPO.xml, click Open, and then click Next.

  12. On the Document Logging page, click Next.

  13. On the Advanced Configuration page, click Finish.

Continue to Create a messaging port to Contoso, Ltd within the buyer system.


Create a messaging port to Contoso, Ltd within the buyer system

This procedure is an example of how to use the File transport service. Because the buyer and the seller systems are both on one computer, we can simulate dropping a file to a location on the seller's system. However, in most cases the buyer would not have access permissions to place a file on a seller's system. Typically, another transport mechanism would be used to send documents to a trading partner, such as HTTP.

In this procedure, the messaging port sends documents processed by the Northwind Traders system to the Contoso, Ltd system by using the File transport service. The documents are sent to the folder specified (C:\TutorialFiles\Seller) in the messaging port destination address.

To create the messaging port:

  1. On the File menu, point to New, point to Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. In the Name box, type Port to Contoso via Local File and click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  4. Click Contoso on Buyer and click OK.

  5. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  6. In the Transport type list, click File.

  7. In the Address box, after file://, type C:\TutorialFiles\Seller\payment%tracking_id%.xml.

    For example, file://c:\TutorialFiles\Seller\payment%tracking_id%.xml.

    Note

    • For the File transport service, the default transport-component setting is to append new files to an existing file in the specified directory. To create a new file with a unique name for each document instance, you must use the following file path format:
      file://C:\dir\file%tracking_id%.xml
  8. Click OK to close the Primary Transport dialog box and click Next.

  9. On the Envelope Information page, click Next.

  10. On the Security Information page, verify that the Create a channel for this messaging port check box is selected.

  11. In the Channel type list, click From an organization and click Finish.

    The New Channel Wizard opens.

Continue to Create a channel from Contoso, Ltd for the buyer system.


Create a channel from Contoso, Ltd for the buyer system

The channel that you create in this procedure processes invoices that are received from Contoso, Ltd and uses a map to transform the invoice into a payment. More specifically, you identify the source of the document, Contoso on Buyer, and specify that the document that is coming in is an invoice, and that the outbound document will be a payment. BizTalk Messaging Services uses the InvoiceToPayment.xml map to transform the document from an invoice to a payment.

If you printed the overview illustration provided at the beginning of this tutorial, you might want to review the visual representation of this process.

To create the channel:

  1. On the General Information page, in the Name box, type Channel for Invoice To Payment and click Next.

  2. On the Source Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  3. Click Contoso on Buyer, click OK, and then click Next.

  4. On the Inbound Document page, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  5. Click Invoice, click OK, and then click Next.

  6. On the Outbound Document page, to the right of the Outbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  7. Click Payment and click OK.

  8. Verify that the Map inbound document to outbound document check box is selected.

  9. To the right of the Map reference box, click Browse.

    The Select a Map from the WebDAV Repository dialog box appears.

  10. Double-click the Microsoft folder.

  11. Click InvoiceToPayment.xml, click Open, and then click Next.

  12. On the Document Logging page, click Next.

  13. On the Advanced Configuration page, click Finish.

  14. On the File menu, click Exit to close BizTalk Messaging Manager.

Continue to Create a File receive function for the buyer system.


Create a File receive function for the buyer system

In this procedure, you create a File receive function that retrieves the buyer's purchase order request from a local file directory and submits it to BizTalk Messaging Services.

Receive functions enable applications to post documents to specific locations that BizTalk Server 2002 is monitoring. In this procedure, you define the location as C:\TutorialFiles\Buyer. The receive function uses event-based monitoring to recognize the presence of a document in that location. Once the document data is received by the function, it submits the data to BizTalk Server. Each document that is submitted to BizTalk Server requires a set of rules for how it is to be processed. In this procedure, you specify the Channel for POReq to PO. This channel contains all the information that the server needs to process the document.

The following illustration shows the relationship between the sending business application, the file system where the file is located, and the receive function.

File receive function

For more information about receive functions, see Understanding Receive Functions and Document Routing.

To create the File receive function:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server 2002, expand BizTalk Server Group, and then click Receive Functions.

  3. On the Action menu, point to New and click File Receive Function.

    The Add a File Receive Function dialog box appears.

  4. In the Name box, type PORequest Receive Function at Northwind Traders.

  5. In the Server on which the receive function will run box, click the name of a server in the BizTalk Server group.

  6. In the File types to poll for box, type *.xml.

  7. In the Polling location box, type C:\TutorialFiles\Buyer.

  8. Click Advanced.

    The Advanced Receive Function Options dialog box appears.

  9. In the Channel name list, click Channel for POReq to PO and click OK.

  10. Click OK to close the Add a File Receive Function dialog box.

  11. Close BizTalk Server Administration.

Continue to Configuring the Seller System.


Configuring the Seller System

In the following procedures, you use BizTalk Messaging Manager to create organizations that represent the trading partners on the Contoso, Ltd system. You also configure the messaging ports and channels that define the movement of documents on that system.

Continue to Create the organizations for the seller system.


Create the organizations for the seller system

In this procedure, you create organizations on the Contoso, Ltd system that will serve as the source for a channel or the destination for a messaging port. For more information, see Understanding Organizations.

Note

  • For the purpose of this tutorial, both the buyer and seller systems are configured on one computer.
  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. On the File menu, point to New and click Organization.

    The New Organization dialog box appears.

  4. On the General tab, in the Organization name box, type Contoso on Seller and click OK.

  5. Repeat steps 3 and 4, naming the new organization Northwind Traders on Seller, and click OK.

Continue to Create a messaging port to Contoso, Ltd for the seller system.


Create a messaging port to Contoso, Ltd for the seller system

In this procedure, you create a messaging port that defines the destination for the PO on the seller's system. This messaging port sends documents internally within the Contoso, Ltd system, using an application integration component (AIC) as the transport service.

An AIC typically serves as an integration point between BizTalk Server 2002 and a back-end application. In this scenario, the AIC functions both as the integration point and as a hypothetical back-end application. The messaging port passes the purchase order to the AIC. When a purchase order is submitted to a seller, there can be several additional business processes that take place before an invoice is generated. However, for the purposes of this tutorial the AIC will perform all the tasks necessary to transform the purchase order into an invoice and submit it to the appropriate channel in BizTalk Messaging Services within the seller system.

The purchase order could also be transformed into an invoice by using a map in the channel, but to demonstrate the use of another transport service the AIC will perform this function in this scenario.

To create the messaging port:

  1. On the File menu, point to New, point to Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. In the Name box, type Port to Contoso via AIC and click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  4. Click Contoso on Seller and click OK.

  5. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  6. In the Transport type list, verify that Application Integration Component is selected and click Browse.

    The Select a Component dialog box appears.

  7. Click POToINVAIC ConvertPOToInvoice and click OK.

  8. Click OK to close the Primary Transport dialog box and click Next.

  9. On the Envelope Information page, click Next.

  10. On the Security Information page, verify that the Create a channel for this messaging port check box is selected.

  11. In the Channel type list, click From an organization and click Finish.

    The New Channel Wizard opens.

Continue to Create a channel from Northwind Traders for the seller system.


Create a channel from Northwind Traders for the seller system

In this procedure, you create a channel for the messaging port.

The channel that you create has as its source organization "Northwind Traders on Seller," which represents the buyer on the Contoso, Ltd system. This channel processes purchase orders that are received from Northwind Traders. Because both the inbound and the outbound document definitions are identical, no map reference is required for this channel and no document transformation occurs.

If you printed the overview illustration provided at the beginning of this tutorial, you might want to review the visual representation of how the channel, messaging port, and AIC transport process the purchase order.

To create the channel:

  1. On the General Information page, in the Name box, type Channel for PO and click Next.

  2. On the Source Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  3. Click Northwind Traders on Seller, click OK, and then click Next.

  4. On the Inbound Document page, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  5. Click Purchase Order, click OK, and then click Next.

  6. On the Outbound Document page, to the right of the Outbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  7. Click Purchase Order, click OK, and then click Next.

  8. On the Document Logging page, click Next.

  9. On the Advanced Configuration page, click Finish.

Continue to Create a messaging port to Northwind Traders for the seller system.


Create a messaging port to Northwind Traders for the seller system

In this procedure, you create a messaging port on the Contoso, Ltd system that defines the destination for the invoice. More specifically, this messaging port sends the invoice from the Contoso, Ltd system to the buyer, Northwind Traders. You will use HTTP as the transport service to deliver the invoice to an ASP page on the Northwind Traders Web server. The ASP page then posts the invoice to the ReceiveInvoice message queue within the buyer's system.

To create the messaging port:

  1. On the File menu, point to New, point to Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. On the General Information page, in the Name box, type Port to Northwind Traders via HTTP and click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  4. Click Northwind Traders on Seller and click OK.

  5. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  6. In the Transport type list, click HTTP.

  7. In the Address box, after the http:// prefix, type the name of your computer followed by /InvoiceToQueue/DropInvoicetoMSMQ.asp, click OK, and then click Next.

    For example, if this message is going to an ASP page on the Northwind Traders Web server you might type, http://NorthwindTraders/InvoiceToQueue/DropInvoicetoMSMQ.asp.

    To find the name of your computer, complete the following steps:

    1. On the Start menu, point to Settings and click Control Panel.

    2. Double-click Administrative Tools.

    3. Double-click Computer Management.

      The Computer Management console appears.

    4. On the Action menu, click Properties.

      The Computer Management (Local) Properties dialog box appears.

    5. Click the Network Identification tab.

      The name of your computer appears in the Computer name field.

  8. On the Envelope Information page, click Next.

  9. On the Security Information page, verify that the Create a channel for this messaging port check box is selected.

  10. In the Channel type list, click From an organization and click Finish.

    The New Channel Wizard opens.

Continue to Create a channel from Contoso, Ltd for the seller system.


Create a channel from Contoso, Ltd for the seller system

The channel that you create in this procedure has as its source organization "Contoso on Seller" because the invoice will come from an internal source after it has been processed and converted from a purchase order. This channel processes invoices that are sent to Northwind Traders internally, on the seller system, according to the rules of the messaging port that you just created, Port to Northwind Traders via HTTP.

If you printed the overview illustration provided at beginning of this tutorial, you might want to review the visual representation of how the channel, messaging port, and HTTP transport service process the invoice.

To create the channel:

  1. On the General Information page, in the Name box, type Channel for Invoice and click Next.

  2. On the Source Organization page, in the Organization area, click Browse.

    The Select an Organization dialog box appears.

  3. Click Contoso on Seller, click OK, and then click Next.

  4. On the Inbound Document page, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  5. Click Invoice, click OK, and then click Next.

  6. On the Outbound Document page, click Browse.

    The Select a Document Definition dialog box appears.

  7. Click Invoice, click OK, and then click Next.

  8. On the Document Logging page, click Next.

  9. On the Advanced Configuration page, click Finish.

  10. On the File menu, click Exit to close BizTalk Messaging Manager.

Continue to Module 3 Summary.


Module 3 Summary

In this module, you configured BizTalk Messaging Services on the buyer and the seller systems. It is important to note the order of events. First you establish the trading partners on each system by creating organizations, and then you define the documents that the organizations will send and receive. Then you work backwards, configuring the destination for the document, the source of the document, and then (for the buyer's system) the receive function that gets the document and submits it to BizTalk Messaging Services.

In this module, you accomplished the following tasks:

  • Created organizations. For more information, see Create and Manage Organizations.

  • Created document definitions. For more information, see Create and Manage Document Definitions.

  • Created messaging ports. For more information, see Create and Manage Messaging Ports.

  • Created channels. For more information, see Create and Manage Channels.

  • Used a map in a channel to transform a document. For more information, see Using BizTalk Mapper.

  • Created a File receive function. For more information, see Receive Functions.

To view the document definitions, organizations, messaging ports, channels, and map that you created in this module, use the Search Now button in BizTalk Messaging Manager.

The highlighted areas of the following illustration show the steps you completed in this module.

Continue to Module 4: Completing the XLANG Schedule.

Related Topic

Using BizTalk Messaging Manager


Module 4: Completing the XLANG Schedule

The initial representation of the Northwind Traders business process covered only the purchase order approval process. The business processes surrounding a purchase order also include sending out an approved purchase order, receiving an invoice, and returning a payment.

In this module, you use BizTalk Orchestration Designer to modify the buyer's XLANG schedule to include the invoice and payment actions, and to implement the necessary ports. You then compile and run the completed XLANG schedule.

Objectives

  • Add invoice and payment actions. For more information, see Add shapes.

  • Implement a port by using BizTalk Messaging Services. For more information, see Using the BizTalk Messaging Shape.

  • Compile and run the completed XLANG schedule. For more information, see Compiling XLANG Schedules and Running XLANG Schedules.

To complete the XLANG schedule, continue to Add invoice and payment actions.

Shortcut

  • If BizTalk Server and all its components are installed on the C drive you can use the existing XLANG schedule. Continue to Run the completed XLANG schedule.

Related Topic

Designing BizTalk Orchestrations


Add invoice and payment actions

In this procedure, you modify the Northwind Traders business process in BizTalk Orchestration Designer by adding an action that receives the invoice from the buyer and another action that sends the payment message to Contoso, Ltd.

To create the actions:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Orchestration Designer.

  2. On the File menu, click Open.

    The Open XLANG Schedule Drawing dialog box appears.

  3. If you are using the existing Buyer1.skv file, in the Open XLANG Schedule Drawing dialog box, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive, click Buyer1.skv, and then click Open.

    If you created the Buyer1.skv file in Module 1, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab, click Buyer1.skv, and then click Open.

    Note

    • You can close the blank drawing that appears in BizTalk Orchestration Designer.
  4. Highlight the connection between the Write PO Request to File action and the End action and press DELETE.

  5. Move the End action down to allow room for two new action shapes.

  6. Drag the Action shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position the shape below the Write PO Request to File action.

  7. Right-click the Action shape and click Properties.

    The Action Properties dialog box appears.

  8. In the Name box, type Receive Invoice and click OK.

  9. Drag the Action shape from the Flowchart stencil in the leftmost column to the Business Process page.

    Position the shape below the Receive Invoice action.

  10. Right-click the Action shape and click Properties.

    The Action Properties dialog box appears.

  11. In the Name box, type Send Payment and click OK.

  12. Connect the Write PO Request to File action to the Receive Invoice action.

  13. Connect the Receive Invoice action to the Send Payment action.

  14. Connect the Send Payment action to the End shape.

Continue to Bind the Message Queuing Service to receive an invoice.


Bind the Message Queuing Service to receive an invoice

In the preliminary setup for this tutorial, you created the ReceiveInvoice message queue to enable Northwind Traders to receive invoice messages. In this procedure, you will add the Messaging Queuing shape to the XLANG drawing and implement a port to the ReceiveInvoice message queue. The Message Queuing shape represents the Message Queuing Service that is used to send or receive messages. The service is configured to monitor a message queue for an invoice. The Receive Invoice action is bound to the Message Queuing Service. When an invoice is dropped to the ReceiveInvoice message queue, it activates the Receive Invoice action. For more information, see Using the Message Queuing Shape.

If you printed the overview illustration provided at beginning of this tutorial, you might want to review the visual representation of how the ASP file, message queue, and Receive Invoice action facilitate the movement of the document.

To bind the Message Queuing Service:

  1. Drag the Message Queuing shape from the Implementation stencil in the rightmost column, to the Business Process page.

    Position the Message Queuing shape so that it is horizontally aligned with the Receive Invoice action.

    The Message Queuing Binding Wizard opens.

  2. On the Welcome to the Message Queuing Binding Wizard page, verify that Create a new port is selected.

  3. In the Create a new port box, type ReceiveInvoice and click Next.

  4. On the Static or Dynamic Queue Information page, verify that Static queue is selected and click Next.

  5. On the Queue Information page, click Use a known queue for all instances.

  6. In the Enter the queue name box, type .\private$\ReceiveInvoice and click Next.

  7. On the Advanced Port Properties page, click Finish.

Continue to Define message properties for the Receive Invoice service.


Define message properties for the Receive Invoice service

In this procedure, you use the XML Communication Wizard to facilitate communication between the Receive Invoice action shape and the ReceiveInvoice port. Through the XML Communication Wizard, you provide specific information and specifications that will be used by the XLANG Scheduler Engine to identify and retrieve the correct message from the queue.

  1. Select the Receive Invoice action and drag the control handle on the right of the Receive Invoice action to the ReceiveInvoice port.

    The XML Communication Wizard opens.

  2. On the Welcome to the XML Communication Wizard page, click Receive and click Next.

  3. On the Message Information page, verify that Create a new message is selected.

  4. In the Message name box, type CommonInvoice and click Next.

  5. On the XML Translation Information page, verify that Receive XML messages from the queue is selected and click Next.

  6. On the Message Type Information page, in the Message type box, type CommonInvoice and click Next.

  7. On the Message Specification Information page, click Finish.

Continue to Bind the BizTalk Messaging Services.


Bind the BizTalk Messaging Services

In this procedure, you add the BizTalk Messaging shape to the drawing and use the BizTalk Messaging Binding Wizard to name the port and specify that the port sends rather than receives documents. The BizTalk Messaging shape represents BizTalk Messaging Services that are used to exchange messages between BizTalk Orchestration Services and BizTalk Messaging Services.

In this procedure, you bind a BizTalk Messaging Service to the XLANG schedule drawing. You also identify the channel in BizTalk Messaging Services that is used to transform the invoice to a payment. For more information, see Using the BizTalk Messaging Shape.

To bind the BizTalk Messaging Services:

  1. Drag the BizTalk Messaging shape from the Implementation stencil in the rightmost column to the Business Process page.

    Position the BizTalk Messaging shape so that it is horizontally aligned with the Send Payment action.

    The BizTalk Messaging Binding Wizard opens.

  2. On the Welcome to the BizTalk Messaging Binding Wizard page, verify that Create a new port is selected.

  3. In the Create a new port box, type SendPayment and click Next.

  4. On the Communication Direction page, verify that Send is selected and click Next.

  5. On the Static or Dynamic Channel Information page, verify that Static channel is selected.

  6. In the Enter the name of a known, pre-existing channel box, type Channel for Invoice To Payment and click Finish.

    Note that Channel for Invoice To Payment was created in Module 3.

Continue to Define message properties for the BizTalk Messaging Services.


Define message properties for the BizTalk Messaging Services

In this procedure, you use the XML Communication Wizard to facilitate communication between the Send Payment action and the SendPayment port.

  1. Drag the control handle on the right of the Send Payment action to the SendPayment port.

    The XML Communication Wizard opens.

  2. On the Welcome to the XML Communication Wizard page, click Next.

  3. On the Message Information page, click Add a reference to an existing message, click CommonInvoice, and then click Next.

  4. On the XML Translation Information page, verify that Send XML messages to the queue is selected and click Next.

  5. On the Message Type Information page, click Next.

  6. On the Message Specification Information page, click Finish.

Continue to Save the completed XLANG schedule drawing.


Save the completed XLANG schedule drawing

  1. On the File menu, click Save As.

    The Save XLANG Schedule Drawing As dialog box appears.

  2. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab on the BizTalk Server installation drive.

  3. In the File name box, type Buyer2 and click Save.

Continue to Compile the completed XLANG schedule.


Compile the completed XLANG schedule

For more information about compiling an XLANG schedule drawing into an executable XLANG schedule, see Compiling XLANG Schedules.

  1. On the File menu, click Make XLANG Buyer2.skx.

    The Save XLANG Schedule to dialog box appears.

  2. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab on the BizTalk Server installation drive.

  3. In the File name box, type Buyer2 and click Save.

    Your completed XLANG schedule drawing should appear similar to the following illustration.

    XLANG schedule drawing

  4. On the File menu, click Exit.

Continue to Run the completed XLANG schedule.


Run the Completed XLANG Schedule

You have completed the configuration of a business-to-business automated procurement solution. You can now run the application that activates the XLANG schedule.

In this procedure, you use the ExecuteTutorial application that activates the XLANG schedule by delivering a purchase order request to the message queue that is being monitored.

To run the XLANG schedule:

  1. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive.

  2. Double-click ExecuteTutorial.exe. This application is used to activate the XLANG schedule by means of a moniker.

    The ExecuteTutorial application opens.

  3. Click Browse for Schedule.

    Shortcut

    • If BizTalk Server and all its components are installed on the C drive you can use the existing XLANG schedule. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution and continue to step 5.
  4. If you created the Buyer2 XLANG schedule, browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab.

  5. Click the Buyer2.skx XLANG schedule and click Open.

  6. Click Browse for Data File and browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\SampleData.

  7. Click POReqAccept.xml and click Open.

  8. Click Start XLANG Schedule.

    Because its total is less than $1000, the purchase order request is approved. A message box appears, notifying you that the application passed data to the XLANG Scheduler Engine. At this point, the application is finished. A second message box notifies you that the purchase order request has been approved. Click OK to close the message boxes.

  9. Click End to close the ExecuteTutorial application.

  10. Browse to C:\TutorialFiles\Seller.

    You see the payment file. The file name is PaymentXXXX.xml, where XXXX is a unique set of numbers. Double-click the file to open it in Microsoft Internet Explorer.

You have submitted a purchase order request. The purchase order request was approved and sent to the seller. The order was filled and an invoice was issued. When the invoice was received, a payment message was posted to the seller system.

Continue to Module 4 Summary.


Module 4 Summary

In this module, you accomplished the following:

  • Added invoice and payment actions. For more information, see Connect Shapes.

  • Implemented a messaging port using BizTalk Messaging Services. For more information about implementing a messaging port using BizTalk Messaging Services, see Using the BizTalk Messaging Shape.

  • Compiled and ran the completed XLANG schedule. For more information, see Compiling XLANG Schedules and Running XLANG Schedules.

The highlighted areas of the following illustration show the steps you completed in this module.

Continue to Tutorial Summary.

Related Topic

Designing BizTalk Orchestrations


Tutorial Summary

In this tutorial you configured Microsoft BizTalk Server 2002 to establish and run a business-to-business automated procurement process.

The following illustration shows the flow of data through BizTalk Server while running the Buyer2 XLANG schedule at the end of Module 4.

Flow of data

You learned how BizTalk Server components and services work together to integrate loosely coupled, long-running business processes, both within and between businesses.

You also learned how to:

  • Use BizTalk Orchestration Designer to model business processes by creating an XLANG schedule drawing.

  • Use BizTalk Messaging Manager to create organizations, channels, messaging ports, and document definitions.

  • Use BizTalk Editor to create specifications.

  • Use BizTalk Mapper to create maps.

  • Compile and run an XLANG schedule.

You have successfully completed the tutorial.

Additional Resources

For detailed information about creating the auxiliary components used in this tutorial, see Appendix: Creating Auxiliary Components.

For a conceptual overview of the fundamental concepts that surround the processes and tasks required to build a business-to-business automated procurement process with BizTalk Server, see Learning BizTalk Server 2002.

For a comprehensive example of how to use several of the new features available in BizTalk Server 2002, see the E-Procurement Sample. The new features include:

  • BizTalk SEED Wizard for rapid partner enablement

  • Application Center deployment capabilities

  • Advanced monitoring capabilities using Microsoft Operations Manager (MOM)

  • New XLANG correlation using common queues instead of per-instance queues


Appendix: Creating Auxiliary Components

In this appendix, you learn how to create auxiliary components that work in conjunction with Microsoft BizTalk Server 2002 to process data. Each component and its role and relationship in the process are described in detail.

Important

  • Microsoft Visual Basic 6.0 is required to complete some of the procedures in this Appendix.

Specifically, you create:

  • An application on the buyer system that activates an XLANG schedule and sends a purchase order (PO) request to a message queue that is bound to the XLANG schedule that controls the flow of messages through the buyer system.

  • A Windows Script Component (WSC) on the buyer system that accepts the approval or denial status for a purchase order request from the XLANG schedule. If approved, the WSC displays an approval message and writes the purchase order request to a local file directory, where the BizTalk Messaging Services for the buyer system retrieves it. If denied, the WSC displays a denial message and the schedule ends.

  • An application integration component (AIC) on the seller system that generates an invoice based on the data in the purchase order from the buyer.

Continue to Creating the Application.


Creating the Application

In this topic, you create an application that activates an XLANG schedule and then drops a purchase order request to a queue. You use this application to test the implementation of the XLANG schedule and the configuration of BizTalk Messaging Manager.

To complete the lab, modify the code in the sample project. You will focus on the code that is specific to activating the XLANG schedule and to dropping a message into a queue. Ancillary code is provided for you.

Each step corresponds to a segment of code. Look for comment blocks similar to the following example:

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'To Do: Step A
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Following this code are lines that have question marks (?) indicating placeholders where you must make a change. Replace the question marks with the proper code to complete the lab. For example:

Private g_MSMTxDisp As ?

should be changed to:

Private g_MSMTxDisp As MSMQ.MSMQTransactionDispenser

Note

  • These lines of code have been commented out. Be sure to remove the comment mark at the beginning of the lines to which you make changes. The steps are not necessarily in order in the code window.

Continue to Open the application.


Open the application

  1. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab on the BizTalk Server installation drive.

  2. Double-click ExecuteTutorial.vbp.

Continue to Add the required references to the application.


Add the required references to the application

In this procedure, you enable the application to implement a number of dynamic-link libraries (DLLs) required to use Message Queuing, XML, and the scripting runtime.

  1. On the Project menu, click References.

  2. Select Microsoft Message Queue 2.0 Object Library.

    The full path for this type library is \WINNT\System32\ MQOA.dll.

  3. Select Microsoft Scripting Runtime.

    The full path for this DLL is \WINNT\System32\Scrrun.dll.

  4. Select Microsoft XML, v 3.0.

    The full path for this DLL is \WINNT\System32\msxml3.dll.

  5. Click OK.

Continue to Define and initialize the Message Queue objects.


Define and initialize the Message Queue objects

In this procedure, you add the code to use the chosen type libraries. The lettered steps in the following list correspond to the lettered steps in the code provided.

  1. In the Project window, expand Forms and click Form1 (ExecuteTutorial.frm).

  2. On the View menu, click Code.

  3. In the General Declarations section at step A in the code, create the Message Queue objects as shown in the following example:
    Private g_MSMTxDisp As MSMQ.MSMQTransactionDispenser
Private g_MSMQQueue As MSMQ.MSMQQueue
Private g_MSMQInfo As MSMQ.MSMQQueueInfo
  4. In the Form_Load event section at step B in the code, initialize the Message Queue objects as shown in the following example:
    Set g_MSMQInfo = CreateObject("MSMQ.MSMQQueueInfo")
Set g_MSMTxDisp = CreateObject("MSMQ.MSMQTransactionDispenser")

Continue to Add code to place data on a queue.


Add code to place data on a queue

In this procedure, you add a new subroutine called ExecuteMSMQ. This routine is called by the cmdRunSked_Click event. You add the code to call this subroutine in the following procedure.

  • Place the following code at the end of the code window in your project at step C:
    Public Sub ExecuteMSMQ(ByVal strQueuePath As String, DataToQueue As String)
    Dim QueueMsg As New MSMQMessage

    Dim strData As String
    Dim fSend As Boolean
    Dim txt As TextStream
    Dim mybyte() As Byte

    g_MSMQInfo.FormatName = strQueuePath
    Set g_MSMQQueue = g_MSMQInfo.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
    mybyte = StrConv(DataToQueue, vbFromUnicode)
    QueueMsg.Body = DataToQueue

    Set MSMQTx = g_MSMTxDisp.BeginTransaction
    QueueMsg.send g_MSMQQueue, MSMQTx
    MSMQTx.Commit

    Set QueueMsg = Nothing
    Set MSMQTx = Nothing

End Sub

Continue to Add code to activate the XLANG schedule and call ExecuteMSMQ.


Add code to activate the XLANG schedule and call ExecuteMSMQ

In this procedure, you add code to the cmdRunSked_Click event that activates the XLANG schedule and calls code that sends a message to a queue.

  1. In the cmdRunSked_Click event section at step D of the code, call ExecuteMSMQ, as shown in the following code:
    ExecuteMSMQ "DIRECT=OS:.\private$\ReceivePOReq", objfs.OpenTextFile(txtData.Text, ForReading).ReadAll
  2. In the cmdRunSked_Click event section at step E of the code, call GetObject to instantiate the XLANG schedule by moniker, as shown in the following code:
    Set SendPAQ = GetObject(txtSked.Text)

Continue to Save and compile the application.


Save and compile the application

In this procedure, you save and compile the application.

  1. On the File menu, click Save Project.

  2. On the File menu, click Make ExecuteTutorial.exe.

    The Make Project dialog box appears.

  3. Browse to the \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab folder on the BizTalk Server installation drive and click OK.

You can now run the application to execute the buyer schedule in Modules 1 and 4.

Continue to Creating the Windows Script Component.


Creating the Windows Script Component

In this topic, you create a Windows Script Component (WSC) that is bound to the XLANG schedule. The purpose of the WSC is to display a message box with approval or denial status of the purchase order request, and to optionally write the purchase order request to a local file if it is approved.

Continue to Add script to register the component.


Add script to register the component

In this procedure, you add script that allows the component to be registered to the file.

  1. On the Start menu, point to Programs, point to Accessories, and then click Notepad.

  2. Add the following script:
    <?xml version="1.0"?>
<component>
<?component error="true" debug="true"?>
<registration
     description="PORequestApproval"
     progid="BTSTutorial.PORequestApproval"
     version="1.00"
     classid="{2938621b-40fc-48e2-827c-bed74e21a538}"
>
</registration>

    Because you are using the same class ID as the preconfigured component, the old component is overwritten in the registry.

Continue to Add script to implement the methods.


Add script to implement the methods

This component exposes three methods. The first method sends an approval status in the form of a message box that is displayed to the user. The second method sends a denial status, also in the form of a message box that is displayed to the user. The decision as to which method is called is dictated by the decision rule in the XLANG schedule drawing. The last method writes the purchase order to a local file if the purchase order request has been approved.

  1. Add the three method signatures to the end of the file:
    <public>
     <method name="SendApproval">
          <PARAMETER name="Document"/>
     </method>
     <method name="SendDenial">
          <PARAMETER name="Document"/>
     </method>
     <method name="WriteToFile">
          <PARAMETER name="Document"/>
          <PARAMETER name="FileName"/>
     </method>
</public>
  2. Add the script that implements the methods to the end of the file:
    <implements type="Behavior" id="Behavior"/>

<script language="VBScript">
<![CDATA[

function SendApproval(Document)
     MsgBox "Scheduler Engine Accepted document :" + vbcrlf + + vbcrlf + Document, 0, "Document Approval Received"
end function

function SendDenial(Document)
     MsgBox "Scheduler Engine Denied document :" + vbcrlf + + vbcrlf + Document, 0, "Document Denied"
end function

function WriteToFile(Document, FileName)
     dim objFileSys, strTimeNow

     if FileName = "" then
            FileName = "c:\TutorialFiles\Buyer\POReq*.xml"
     end if

'Generate a Unique Number used to generate unique files using a mask
   strTimeNow = left(Replace(CStr(FormatDateTime(Now(), 3)),":",""), 6)

'Create File System Object
     Set objFileSys = CreateObject("Scripting.FileSystemObject")

'Create the Specified file, write the document data and close
     Set filestream = objFileSys.CreateTextFile(Replace(FileName, "*", strTimeNow), False)
     filestream.writeline Document
      filestream.close
end function

]]>
</script>

</component>
  3. On the File menu, click Save As.

    The Save As dialog box appears.

  4. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POReqApproval\Lab on the BizTalk Server installation drive.

  5. In the File name box, type PORequestApproval.wsc.

  6. In the Save as type box, click All Files and click Save.

  7. Close Notepad.

  8. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POReqApproval\Lab.

  9. Right-click PORequestApproval.wsc and click Register.

This component can be substituted for the preconfigured WSC used in Module 1. To use this component, you must remove the existing WSC binding from the schedule and then create a new WSC binding that points to your component.

Continue to Delete the WSC component.


Delete the WSC component

In this procedure, you delete the WSC component from the Buyer2 XLANG schedule drawing. You can rebind the component you have created.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Orchestration Designer.

  2. To use the drawing created in Module 4, open the Buyer2.skv file located at \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Lab on the BizTalk Server installation drive.

    To use the existing Buyer2 drawing, open the Buyer2.skv file located at \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution.

  3. Click the Script Component shape and press DELETE.

  4. Click the Data tab.

  5. Delete the SendApproval, SendDenial, and WritetoFile messages.

You are now ready to use your WSC component in the schedule. Do the following:

  1. Implement a port to Buyer2.skv by using your WSC component.

    For an example of how to do this, see Implement a port by using a script component. However, use your component instead of the component in the procedure.

  2. Define the method communication for the port implementation.

    For an example of how to do this, see Define message properties for the script component.

  3. Define the data flow for the port.

    For an example of how to do this, see Define the data flow.

  4. Save the XLANG file.

    For an example of how to do this, see Save the XLANG schedule drawing.

  5. To test your component, run the ExecuteTutorial application located at \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive.

Continue to Creating the Application Integration Component (AIC).


Creating the Application Integration Component (AIC)

In this topic, you create a new application integration component called POtoINVAIC that converts a purchase order document into an invoice document by using the MSXML DOM.

Continue to Create an ActiveX DLL project for the AIC.


Create an ActiveX DLL project for the AIC

  1. Start Microsoft Visual Basic 6.0.

  2. In the New Project dialog box, click the New tab, click ActiveX DLL, and then click Open.

    This creates a new project for your component, called Project 1.

  3. To rename both the project and the control to something more meaningful, in the project tree window, click Project1 and, in the properties window, change the (Name) property to POtoInvAICLab.

  4. In the project tree window, click Class1(Class1) and, in the properties window, change the (Name) property to ConvertPOtoInvoice.

Continue to Add the required references for the AIC.


Add the required references for the AIC

In this procedure you enable the component to implement a number of interfaces required by BizTalk Server 2002.

  1. On the Project menu, click References.

  2. Click Microsoft BizTalk Server Application Interface Components 1.0 Type Library.

    The full path for this type library is \Program Files\Microsoft BizTalk Server\btscomplib.tlb.

  3. Select Microsoft BizTalk Server Interchange 1.0 Type Library.

    The full path for this type library is \Program Files\Microsoft BizTalk Server\cisapi.tlb.

  4. Select Microsoft Scripting Runtime.

    The full path for this DLL is \WINNT\System32\Scrrun.dll. Use this library to create a file system object and open a text stream that is used to write a purchase order to disk.

  5. Select Microsoft XML, v 3.0.

    The full path for this DLL is \WINNT\System32\msxml3.dll.

  6. Click OK.

Continue to Implement the required interface.


Implement the required interface

For BizTalk Server to recognize a component as an AIC, it must implement one of two interfaces. For the purposes of this tutorial, you implement the IBTSAppIntegration interface.

  1. In the Project window, click the ConvertPOtoInvoice class module.

  2. On the View menu, click Code.

  3. Add the following line of code at the top of the code window to ensure that all variables are explicitly declared to minimize simple errors:
    Option Explicit
  4. Implement the required interface by adding the following line of code after the Option Explicit statement:
    Implements IBTSAppIntegration

Continue to Define and initialize the class objects.


Define and initialize the class objects

In this procedure, you add code to define the MSXML class objects to create the XML files using the DOM. You will create a string variable that points to the project style sheet that converts a purchase order into an invoice.

  1. Place the following code beneath the Implements IBTSAppIntegration statement:
    'Class Object Defines
Private m_DOMCommonPO As MSXML2.DOMDocument
Private m_DOMStylesheet As MSXML2.DOMDocument
Private m_objSubmit As BTSInterchangeLib.Interchange

'Embedded Project Stylesheet to Convert CommonPO to CommonInvoice
Private m_strStylesheet As String
  2. Add the following code to initialize the XML DOM objects that will convert the purchase order to an invoice, as well as the Interchange object that submits the final invoice document to BizTalk Server:
    Private Sub Class_Initialize()
'Create DOM/Interchange Objects
    Set m_DOMCommonPO = New MSXML2.DOMDocument
    Set m_DOMStylesheet = New MSXML2.DOMDocument
    Set m_objSubmit = New BTSInterchangeLib.Interchange

'Configure DOM Objects to be Synchronous
    m_DOMCommonPO.async = False
    m_DOMStylesheet.async = False

'Fill Stylesheet Embedded String
    m_strStylesheet = m_strStylesheet + ""

End Sub

Continue to Implement the interface method.


Implement the interface method

The ProcessMessage method of the IBTSAppIntegration interface takes an incoming XML common purchase order document transmitted from BizTalk Server and performs a translation on the data to convert it into an XML common invoice document. The common invoice document is then submitted back to BizTalk Server. The intent is to simulate a back-end system that receives purchase orders and eventually returns an invoice for those purchase orders.

  1. Add the function definition and dimension variables, as in the following code:
    Private Function IBTSAppIntegration_ProcessMessage( _
                                ByVal bstrDocument As String) As String
    Dim bstrInvoiceDocument As String
    Dim objScripting As New Scripting.FileSystemObject
'Initialize ProcessMessage to null
    IBTSAppIntegration_ProcessMessage = ""
  2. Add the code to load the received data into a DOM object and validate that it is in the proper format by adding the following code beneath the IBTSAppIntegration_ProcessMessage statement:
        m_DOMCommonPO.loadXML bstrDocument

    If m_DOMCommonPO.parseError.errorCode <> 0 Then 'The data was not valid XML
'Raised errors are not caught in the component, and will be sent back to BizTalk Server
        Err.Raise m_DOMCommonPO.parseError.errorCode, "AICSample.ConvertPOToInvoice Component", _
            "The provided document was not valid XML and could not be processed because:" + _
            vbCrLf + vbCrLf + m_DOMCommonPO.parseError.reason + vbCrLf + " on line: " + _
            CStr(m_DOMCommonPO.parseError.Line) + vbCrLf + "at position: " + _
            CStr(m_DOMCommonPO.parseError.linepos)
    End If
  3. Add code to use the resource file that contains XSL code that converts a purchase order to an invoice by adding the following code beneath the End If statement:
        If m_strStylesheet = "" Then
        m_strStylesheet = StrConv(LoadResData(101, "CUSTOM"), vbUnicode)

    End If
    m_DOMStylesheet.loadXML m_strStylesheet
    bstrInvoiceDocument = m_DOMCommonPO.transformNode(m_DOMStylesheet)

    If bstrInvoiceDocument = "" Then ' Mapping Failed Raise an Error
        Err.Raise vbObjectError + 100, "AICSample.ConvertPOToInvoice Component", _
            "The provided CommonPO document could not be translated into a Common Invoice " + _
            "as the map produced blank output."
    End If
  4. Add code to submit the invoice document to BizTalk Messaging Services by adding the following code beneath the End If statement:
    IBTSAppIntegration_ProcessMessage = m_objSubmit.Submit(BIZTALK_OPENNESS_TYPE_NOTOPEN, bstrInvoiceDocument, , , "Contoso on Seller", , "Northwind Traders on Seller")

End Function

    The submit call returns the submission ID, which in this case is not used.

Continue to Terminate the class objects.


Terminate the class objects

To ensure that all objects are released from memory when the class terminates, add this code to the end of your project:

Private Sub Class_Terminate()
    Set m_DOMCommonPO = Nothing
    Set m_DOMStylesheet = Nothing
    Set m_objSubmit = Nothing
End Sub

Continue to Create the resource file.


Create the resource file

In this procedure, you add the resource file that contains the XSL for transforming a purchase order into an invoice.

  1. On the Add-Ins menu, click Add-In Manager.

    The Add-In Manager dialog box appears.

  2. Click VB 6 Resource Editor.

  3. In the Load Behavior area, click Loaded/Unloaded to load the resource editor, click Load on Startup, and then click OK.

  4. On the Tools menu, click Resource Editor.

  5. Click the Add Custom Resource icon on the tool bar.

    The Open a Custom Resource dialog box appears.

  6. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POtoInvoice\Lab on the BizTalk Server installation drive, click POtoINVAIC.txt, and then click Open.

    Caution

    • Make sure that the ID of your resource is 101. By default, the first resource you create has an ID of 101, but this number increments by one if you change the resource. To change the resource ID to 101, right-click the resource ID and click Properties. In the ID box, type 101.
  7. Click the Save icon.

    The Save Resource File As dialog box appears.

  8. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POtoInvoice\Lab.

  9. In the File name box, type POtoInvAICLab.RES and click Save.

  10. Close the Resource Editor.

Continue to Build the component and set binary compatibility.


Build the component and set binary compatibility

Because you are creating a new component, you must build the component at this point, and then set the project properties for binary compatibility with the newly created DLL. Binary compatibility ensures that each time you compile the DLL you do not generate a new globally unique identifier (GUID) for the object.

  1. On the File menu, click Save Project As.

    The Save File As dialog box appears.

  2. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POToInvoice\Lab on the BizTalk Server installation drive.

  3. In the File name box, type ConvertPOtoInvoice.cls and click Save.

    The Save Project As dialog box appears.

  4. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POToInvoice\Lab.

  5. In the File name box, type POToInvAICLab and click Save.

  6. On the File menu, click Make POToInvAICLab.dll.

    The Make Project dialog box appears.

  7. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POtoInvoice\Lab and click OK.

  8. On the Project menu, click POToInvAICLab Properties.

  9. Click the Component tab.

  10. Click Binary Compatibility.

  11. Click the browse button (...) to locate \Program Files\Microsoft BizTalk Server\Tutorial\Components\POtoInvoice\Lab.

  12. Click POToInvAICLab.dll and click Open.

  13. Click OK.

Continue to Register the AIC.


Register the AIC

In this procedure, you register the AIC so that BizTalk Server can recognize it. BizTalk Server looks at the list of registered COM components and then queries those components to determine which of them implement either the IBTSAppIntegration interface or the IPipelineComponent interface. All components that meet this criteria are displayed in a list of components in BizTalk Messaging Manager.

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Component Services.

    The Component Services console appears.

  4. In the console tree, expand Component Services, expand Computers, expand My Computer, and then click COM+ Applications.

  5. Right-click COM+ Applications, point to New, and then click Application.

    The COM Application Install Wizard opens.

  6. On the Welcome to the COM Application Install Wizard page, click Next.

  7. On the Install or Create a New Application page, click Create an empty application.

  8. In the Enter a name for the new application box, type POToInvAICLab.

  9. In the Activation type area, click Server application and click Next.

  10. In the Account area, click Interactive User-the current logged on user and click Next.

  11. Click Finish.

  12. In the console tree, expand COM+ Applications and expand the new package you created, called POToInvAICLab.

  13. Click Components.

  14. Browse to \Program Files\Microsoft BizTalk Server\Tutorial\Components\POtoInvoice\Lab on the BizTalk Server installation drive.

  15. Drag POToInvAICLab.dll to the Components folder in Component Services.

  16. Close Component Services.

You can now reconfigure the port to use the new AIC, using the following steps:

Note

  • The current logged on user must be a member of the BizTalk Server Administrators group and must remain logged on while running this scenario.
  1. Open BizTalk Messaging Manager.

  2. In the Search area, click Messaging ports and click Search now.

  3. In the Messaging port name list, double-click Port to Contoso via AIC.

  4. On the General Information page, click Next.

  5. On the Destination Organization page, in the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  6. Click Browse.

  7. In the Available Components list, click POToInvAICLab ConvertPOtoInvoice and click OK.

  8. Click OK to close the Primary Transport dialog box and click Finish.

  9. Test your component by running the ExecuteTutorial application located at \Program Files\Microsoft BizTalk Server\Tutorial\Schedule\Solution on the BizTalk Server installation drive.


Learning BizTalk Server 2002

Over the course of these lessons you will learn how Microsoft® BizTalk™ Server 2002 can help your business exchange a variety of documents with business partners, as well as integrate internal business processes and applications.

These lessons explain the fundamental concepts surrounding BizTalk Server, and also provide you with information that will help you understand the tools and processes that are required to start building solutions with BizTalk Server.

Note

  • For a step-by-step tutorial of how to configure BizTalk Server processes, see the BizTalk Server 2002 Tutorial. The BizTalk Server Tutorial shows you how to use BizTalk Editor, BizTalk Mapper, BizTalk Messaging Manager, BizTalk Server Administration, and BizTalk Orchestration Designer to configure BizTalk Server to run a business-to-business automated procurement process. For more information about BizTalk Server in general, see Introducing Microsoft BizTalk Server 2002.

Requirements

To use this tutorial, BizTalk Server and all its components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files.

Before running this tutorial, you must also copy the LearnBizTalk directory to your C drive:

  1. Copy the \Program Files\Microsoft BizTalk Server\SDK\LearnBizTalk directory to C:\LearnBizTalk.

  2. Browse to C:\LearnBizTalk\Documents.

  3. While pressing CTRL, select ReqToApprove.xml and ReqToDecline.xml.

  4. Right-click the selection and click Properties.

  5. On the General tab, in the Attributes area, clear the Read-only check box.

  6. Click OK.

Important

  • There are several scripts located in the C:\LearnBizTalk\Scripts directory. You can run the script files by double-clicking them. These scripts make configuration changes within your BizTalk Server installation to help you complete the lessons. Running these scripts may take several minutes. A message box will be displayed when each script is completed.

  • When you are finished with the tutorial, you can run the CleanUp.vbs script to remove all of the changes.

Contents

  • Lesson 1: Introduction to BizTalk Server

  • Lesson 2: Configuring BizTalk Messaging Services

  • Lesson 3: Designing BizTalk Orchestration Services

  • Lesson 4: Understanding Implementation

  • Lesson 5: Using BizTalk Mapper

  • Lesson 6: Sending and Receiving Documents

  • Lesson 7: Completing the Transaction


Lesson 1: Introduction to BizTalk Server

This lesson provides an overview of BizTalk Server and the scenario used throughout the lessons.

The following topics are covered in this lesson:

  • What is BizTalk Server?

  • Why Use BizTalk Server?

  • Why Use XML?

  • Integrated Solutions

  • Installing BizTalk Server

  • The Scenario

  • Running the Scenario


What Is BizTalk Server?

Microsoft BizTalk Server 2002 provides a development and execution environment that orchestrates business processes, both within and between businesses. BizTalk Server can handle business transactions that run as long as weeks or months.

BizTalk Server 2002 features include the ability to define business document specifications and how these documents have to be transformed when passed between applications, and the ability to monitor and log server activity.

The server provides a standard gateway for sending and receiving documents across the Internet, as well as providing a range of services that ensures data integrity, delivery, and security.

Continue to Why Use BizTalk Server?


Why Use BizTalk Server?

In today's business environment it is imperative to ensure that the solution you build is based on commonly accepted protocols and document formats. It is also important to know that your solution will enable integration with the widest variety of business partners and applications, will work securely over the Internet, and will scale as your business needs grow. Microsoft BizTalk Server 2002 is designed to address these issues.

Today's global marketplace dictates a need to efficiently operate 24 hours a day, seven days a week. Customers are more sophisticated and want to stay informed in real time, which translates into an accelerated pace of business and the need for faster decision-making processes. In addition, business relationships have become highly dynamic, and new customers and partners expect businesses to adapt quickly.

There is also a need to support multiple applications on a variety of platforms, and to integrate with business partners using the Internet, extranets, business-to-business (B2B) exchanges, and other resources. Existing information-technology investments need to be preserved, which requires having the ability to support legacy systems and Electronic Data Interchange (EDI) networks like X12 and EDIFACT. And, perhaps most importantly, to effectively compete in today's market, you need to be able to build new solutions quickly, using open Internet standards and technology to assure maximum interoperability. For more information, see Supporting Standards.

BizTalk Server uses XML internally to define the data and structure of your business documents, and it uses standard Internet protocols like Hypertext Transfer Protocol (HTTP) and Simple Mail Transfer Protocol (SMTP) to deliver these documents to their destinations, enabling you to interoperate with various applications running in any environment as long as those applications support Internet standards. You can send documents to BizTalk Server as Extensible Markup Language (XML), EDI, or flat files.

Continue to Why Use XML?


Why Use XML?

To exchange documents in an environment where neither side wants to depend on the technology the other side is using, businesses need to choose a common language in which to write these documents. Extensible Markup Language (XML) has become this common language.

XML is a flexible way to create common information formats and share both the format and the data on the Web. A document that is written in XML can be viewed and edited with any text editor, and is usually easy to understand. In the following example, a company called Northwind Traders is ordering two monitors from a company called Contoso, Ltd. Review the following internal requisition request from Northwind Traders, which is represented in XML format:

<NorthwindReq>
<Header reqNumber="IL0829" reqStatus="New" dateCreated="2000-10-24"/>
<Shipping
name="Brian H. Valentine"
addr1="1234 Main Street"
city="Anytown"
state="AL"
zip="12345"
country="USA"
phone="(555)555-0123" />
<Items count="2">
<Item partNo="270FS" description="27-inch flat screen monitor" qty="2" />
</Items>
</NorthwindReq>

This document follows a predefined format, called a schema. A schema is an XML document that describes the format of other XML documents. Unlike other XML documents, a schema does not contain any data. It contains only the formatting rules for document elements that might appear in a corresponding XML document.

XML has been through a formal standardization process by the World Wide Web Consortium (W3C). XML has reached the level of "W3C Recommendation," the highest level that W3C assigns. For more information about the XML recommendation, go to the Extensible Markup Language (XML) page on the World Wide Web Consortium Web site (www.w3.org/XML).

Microsoft BizTalk Server 2002 also defines documents using a format known as XML-Data Reduced (XDR), a functional subset of the W3C XML Schema effort, which gives you many of the benefits of XML Schema. W3C XML recently reached the level of "W3C Recommendation" and future versions of BizTalk Server will support XML Schema while providing a seamless migration path for existing XDR. For more information about XML Schema, go to the XML Schema page on the World Wide Web Consortium Web site (www.w3.org/XML/Schema).

Continue to Integrated Solutions.


Integrated Solutions

Microsoft BizTalk Server addresses the two key aspects of any document exchange, messaging and orchestration.

BizTalk Messaging Services provides the ability to send business documents securely and reliably. An example of such a document could be a purchase order sent to your supplier, or a request for a price quote on the same product sent to multiple suppliers in order to select the lowest bidder.

BizTalk Orchestration Services enables you to define the business processes that are used to create the message and then implement them using a highly integrated graphical environment. Processes defined using BizTalk Orchestration Services have the key characteristic that they are easy to modify when the business changes, providing you with the agility to respond to those changes.

Because most business processes involve sending and receiving documents and applying business rules to the process, BizTalk Messaging Services and BizTalk Orchestration Services are designed to work together to enable you to create integrated solutions.

Continue to Installing BizTalk Server.


Installing BizTalk Server

In the following lessons you will work through a sample scenario where Northwind Traders is buying computer equipment from Contoso, Ltd. These lessons will explain what happens in each step of the process, and show you how to define formats for the business documents in XML using BizTalk Editor, how to describe internal business processes using BizTalk Orchestration Designer, and how to tie it all together. While there is no coding specific to BizTalk Server integration, you still need to build your own business-specific rules; however, in these lessons the coding required is minimal.

The examples used in the lessons are designed to be installed and run on a single computer; however, you can also configure the same scenario on two or more servers.

Before you install Microsoft BizTalk Server 2002, make sure you have read the Readme.htm and Installation Guide.htm documents, observing the following prerequisites:

  • You must have a computer running Microsoft® Windows® 2000 with Service Pack 2 or later (Windows 2000 Professional and Windows 2000 Server both work), including Internet Information Services (IIS) and Message Queuing, and an account with administrative rights on that computer.

  • You must have Microsoft SQL Server™ 7.0 with Service Pack 3 or SQL Server 2000 with Service Pack 1. You must configure SQL Server for Windows authentication.

  • Microsoft Visio® 2002 must be installed on the computer where you are installing BizTalk Server.

  • In Administrative Tools, in Internet Services Manager, the Enable authoring check box on the Server Extensions tab of the Default Web Site Properties dialog box must be cleared. For more information, see Configure IIS settings for BizTalk Server 2002.

  • To run the scripts for these lessons, you need to install the Message Queuing component of Windows 2000.

For detailed information about the installation process, see Installing BizTalk Server 2002.

Continue to The Scenario.


The Scenario

A computer hardware retailer, Northwind Traders, is ordering computer parts from one of its suppliers, Contoso, Ltd. An internal procurement application at Northwind Traders creates a purchase requisition, just like the one shown in Why Use XML?, and writes it as a file on a hard disk. Microsoft BizTalk Server 2002 monitors the file location and, when it detects a purchase requisition, passes this file to Northwind Traders' automated order approval process. If the requisition is declined, it is marked as such and written as a file on a hard disk. If it is approved, a purchase order is generated and sent to Contoso, Ltd using HTTP protocol. In this scenario, a requisition is always approved if it does not exceed $1,000, and is declined otherwise.

In this scenario, both businesses are using BizTalk Server. While servers running BizTalk Server work well with each other, you can also use BizTalk Server to interact with businesses that are not using this application.

After BizTalk Server on the Contoso, Ltd side receives the purchase order (in this scenario the same instance of BizTalk Server is used to perform tasks for both sides), it passes the purchase order to the Contoso, Ltd business process, which generates an invoice to be delivered to Northwind Traders, again using HTTP. Finally, BizTalk Server on the Northwind Traders side receives the invoice and writes it as a file on a hard disk.

The following illustration shows what this process looks like at a high level.

Process overview for the Learning BizTalk tutorial

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To configure BizTalk Server for the tutorial

  1. Browse to C:\LearnBizTalk\Scripts and double-click Setup.vbs.

    This script file configures BizTalk Server for use during these lessons. Depending on your server environment, the script might take a few minutes to complete, which will be indicated by a message box.

  2. Browse to C:\LearnBizTalk\Documents and double-click ReqToApprove.xml and ReqToDecline.xml to open each file in Microsoft Internet Explorer.

    Notice that the reqStatus field is set to New, and note the values of the totalPrice and reqNumber fields in each document.

To see BizTalk Server process the document

  1. Copy the file ReqToDecline.xml from the C:\LearnBizTalk\Documents directory into the C:\LearnBizTalk\Pickup directory.

    Note

    • Do not move the file because it will be processed by BizTalk Server and removed from the \Pickup directory. Because the order total in this requisition exceeds $1,000, it gets declined and a message box is displayed.
  2. Copy the file ReqToApprove.xml from the C:\LearnBizTalk\Documents directory into the C:\LearnBizTalk\Pickup directory.

    This time the requisition is approved, a purchase order is generated and sent to Contoso, Ltd, the purchase order is processed, an invoice is created and sent back to Northwind Traders, and finally an invoice is received at Northwind Traders and written as a file to the C:\LearnBizTalk\Output directory.

  3. In the \Output directory, double-click the ContosoInvoice.xml file to open it in Internet Explorer.

    The value of the referenceNumber field is now the same as the original reqNumber field.

In the lessons that follow, we take a closer look at what happens in each step of this process, and how to configure BizTalk Server to perform all the necessary tasks.

Continue to Lesson 2: Configuring BizTalk Messaging Services.


Lesson 2: Configuring BizTalk Messaging Services

This lesson reviews the individual steps of the scenario that was set up in Lesson 1. In the remaining lessons you will run additional script files. These scripts make adjustments to the Microsoft BizTalk Server 2002 configuration that was originally created, so you can see the results of individual steps in the process rather than the complete process that was shown in Lesson 1.

The following topics are covered in this lesson:

  • Configuring BizTalk Messaging Services

  • Configuring File Receive Functions

  • Configuring Messaging Ports and Channels

  • Defining Document Specifications

  • Running the Scenario


Configuring BizTalk Messaging Services

BizTalk Messaging Services provides a way to pass documents between internal applications and between external business partners. BizTalk Messaging Services enables you to define how your documents are received, processed, and delivered to their destination, as well as provides such essential features as validating document structure, digital signatures, and encryptions, and guaranteeing delivery over unreliable transports.

The script file L2Prep.vbs alters the configuration of BizTalk Messaging Services, so instead of delivering the document to BizTalk Orchestration Services, it writes it as a file that you can examine.

To run this script

  • Browse to C:\LearnBizTalk\Scripts and double-click L2Prep.VBS.

The following illustration shows how the document is processed.

Continue to Configuring File Receive Functions.


Configuring File Receive Functions

The File receive functions enable you use a file that was created by an internal application with BizTalk Messaging Services. One advantage of working with an output file is that an internal business application that creates this file does not need to communicate with BizTalk Server. It simply creates a file containing the document and posts it to a specific location that BizTalk Server is monitoring, and BizTalk Server picks it up. If you can create output files and receive input files into your existing applications, you might be able to use them with BizTalk Server without a single modification.

Another important aspect of using File receive functions is asynchronous processing. Asynchronous, meaning "not at the same time," pertains to processes that proceed independently of each other. Using asynchronous processing is important in a distributed environment, because it enables each part of the solution to work by itself and not be affected if another part of the solution is temporarily unavailable, whether due to failure or scheduled maintenance.

For example, if you experience a brief network failure, the overall application is not affected because the documents produced by your internal business applications simply accumulate on the hard drive. When the network is available again, BizTalk Server picks up and processes all the files it finds in the designated directory. You can also add more BizTalk Servers and configure them to process documents from the same directory, if you generate more documents than one server can process at an acceptable speed.

To see how the File receive function is configured

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server 2002, expand BizTalk Server Group, expand Receive Functions, right-click ReceiveReq, and then click Properties.

    The ReceiveReq Properties dialog box appears.

  3. After reviewing the General tab, select the Services tab.

    The following illustration shows Services tab, which indicates that the function was configured as a File receive function and that the directory to poll for files and the file types to pick up have been specified.

    ReceiveReq Properties dialog box

    The Advanced tab specifies where BizTalk Server will deliver the files it finds. It also identifies a channel to which the receive function will pass the documents called Channel To Approval. Channels, as well as related messaging ports, are covered in the next section. For more information, see Understanding Receive Function Advanced Properties.

  4. Close the ReceiveReq Properties dialog box.

  5. Close BizTalk Server Administration.

Note

  • File receive functions are not the only way to submit documents to BizTalk Server. You can also receive documents from Message Queuing, through e-mail (SMTP), and from Web pages (HTTP/HTTPS), as well as from a Component Object Model (COM) from within your own applications. For more information, see Available Receive Functions.

Continue to Configuring Messaging Ports and Channels.


Configuring Messaging Ports and Channels

To deliver the document to a destination, you must define the destination in BizTalk Messaging Services. Destinations are known in BizTalk Messaging Services as messaging ports. A messaging port also contains a set of properties with which you can direct how documents are secured and transported to their destination, be it an internal application or an external business partner.

Note

  • You can group messaging ports into distribution lists to send the same document to several different destinations, whether they are business partners or internal applications.

The messaging port that was defined when you ran the setup script is called Req Approval Port. This is a messaging port to an internal application that represents the Northwind Traders business process for requisition approval.

To view the messaging port properties

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. Click Messaging ports and click Search Now.

  3. In the right pane, double-click Req Approval Port to edit it.

    The Messaging Port Properties page appears.

  4. Click Next.

    The Destination Organization page appears.

    In the following illustration, the Destination Organization page shows that this document will be delivered to a file.

    Destination Organization page in the Messaging Port Properties Wizard

In Lesson 1, this messaging port delivered the message to an XLANG schedule within BizTalk Orchestration Services, which implements the approval process. (BizTalk Orchestration Services is covered in more detail in the next lesson.) This was changed by running the script at the start of the lesson, so you can now see the output.

Instead of delivering a document to BizTalk Orchestration Services or to a file, you can configure a messaging port to deliver documents using any of the supported protocols, which include HTTP/HTTPS, SMTP, Message Queuing, and custom application integration components (AICs).

You can also configure a messaging port with extra security features by optionally encrypting your document and/or adding a digital signature to it.

Next, you will define a channel through which this document is delivered. A channel contains a set of properties, which identifies the source organization or application that has sent out the document and defines the specific steps that are performed by BizTalk Server before the document is delivered to the messaging port with which the channel is associated. The following illustration shows the relationships between receive functions, channels, and messaging ports.

Receive functions, channels, and messaging ports

To see how the channel that delivers requisitions to the Northwind Traders approval process is set up

  1. Open BizTalk Messaging Manager if it is not already open.

  2. Click Channels and click Search Now.

  3. In the right pane, double-click Channel To Approval to edit it.

    The Channel Properties page appears.

  4. Click Next.

    Note

    • Alternatively you can select the messaging port Req To Approval by right clicking it and clicking Find Channels on the Edit menu. This will show you all the channels. Only Channel To Approval is connected to Req To Approval.

    In the following illustrations, note that the documents to be processed by this channel will originate from an internal purchasing application, and that these documents will be in a format described by a document definition named Northwind Req.

    Source Application page in the Channel Properties Wizard

  5. Click Cancel to close the Channel Properties page.

  6. Close BizTalk Messaging Manager.

Note

  • You can optionally instruct a channel to translate a document from one document definition into another, as well as specify which information must be logged for tracking purposes as the channel delivers documents. Lesson 5 contains more information about document translation using BizTalk Mapper.

For more information about messaging ports and channels, see Understanding Messaging Ports and Understanding Channels.

The following topic discusses what the document definition is and how to create one.

Continue to Defining Document Specifications.


Defining Document Specifications

Lesson 1 explained how important it is for businesses to use the same language for describing the documents that are passed between them. This common language is XML. Although XML documents are stored in a text format and can be opened with any text editor, creating or modifying them manually can be a tedious and error-prone process. BizTalk Server provides a tool called BizTalk Editor that simplifies this task.

To open the NorthwindReq.xml file

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

  2. On the File menu, click Open.

  3. Browse to C:\LearnBizTalk\Documents, select NorthwindReq.xml, and then click Open.

    The file will open in BizTalk Editor and it will appear as shown in the following illustration.

    NorthwindReq.xml opened in BizTalk Editor

BizTalk Editor provides an easy way to manage specifications, including being able to visualize the format of a document, to define data types for individual elements and attributes, and to define which data fields are required and which are optional. This particular document schema represents an XML document, but BizTalk Editor looks similar for electronic data interchange (EDI) and flat-file schemas.

Because you can work with the document specification on any workstation where you have BizTalk Editor installed, after the specification has been created it also needs to be added to the BizTalk Server WebDAV repository so that BizTalk Server can retrieve it.

Note

  • Web Distributed Authoring and Versioning (WebDAV) is the Internet Engineering Task Force (IETF) standard for collaborative authoring on the Web. It facilitates collaborative editing and file management between users located remotely from each other on the Internet. For more information about WebDAV, go to the "HTTP Extensions for Distributed Authoring -- WEBDAV" document on the IETF Web site (ietf.org/rfc/rfc2518.txt).

To create the document definition, you need to associate a specific XML specification that is created in BizTalk Editor and stored in WebDAV with a name to be used by BizTalk Server.

To create a document definition

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. On the File menu, point to New and click Document Definition.

    The New Document Definition dialog box appears.

  4. In the Document definition name box, type a name for the document definition.

  5. Select the Document specification check box and click Browse.

    The Select a Document Specification from the WebDAV Repository dialog box appears.

  6. Double-click the Microsoft folder, click the schema you want, and then click Open.

    In this dialog box you can choose any schema stored in the BizTalk Server WebDAV repository.

  7. Click OK to save the new document definition.

  8. Close BizTalk Messaging Manager.

Note

  • You can create multiple document definitions that are based on the same schema document. You can optionally define global document tracking options for each document definition that you create. For more information, see Understanding Document Definitions.

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To run the scenario

  1. Copy the file ReqToApprove.xml from C:\LearnBizTalk\Documents into C:\LearnBizTalk\Pickup.

    The File receive function ReceiveReq that you defined previously will pick up that file and deliver it to the Req Approval Port messaging port through the Channel To Approval channel.

  2. Browse to C:\LearnBizTalk\Output and double-click the NorthwindRequisition.xml file to open it in Internet Explorer.

    Note that it is the same document that you pasted into the \Pickup directory. At the beginning of this lesson you ran the L2Prep.VBS script that modified the channel and messaging port definitions. So instead of delivering the requisition document to BizTalk Orchestration Services, the messaging port wrote the document contents to a file called NorthwindRequisition.xml in the \Output directory.

  3. Perform these steps again, this time using the ReqToDecline.xml file. The file in the \Output directory will be overwritten with your newly submitted requisition.

This lesson provided a basic overview of the way BizTalk Messaging Services functions. You ran a script that configured the services, reviewed the properties involved, and picked up a file from the file system in one directory and deposited it in another directory. Now that you understand the basic concepts and terminology, the following lessons will show you some additional features.

The next lesson covers how Northwind Traders' requisition approval process is defined using BizTalk Orchestration Services.

Continue to Lesson 3: Designing BizTalk Orchestration Services.


Lesson 3: Designing BizTalk Orchestration Services

This lesson provides an overview of how Northwind Traders will implement their requisition approval process using BizTalk Orchestration Services. The following illustration gives a detailed view of the requisition approval process.

Lesson 3 process preview

The following topics are covered in this section:

  • BizTalk Orchestration Services

  • Defining the Business Process

  • Implementing the Business Process

  • Creating the Communication Flow

  • Running the Scenario


BizTalk Orchestration Services

Microsoft BizTalk Server 2002 solves two problems: it provides you with BizTalk Messaging Services to send messages between business processes, and it provides you with BizTalk Orchestration Services to create your business processes. The previous lesson outlined how to submit your business documents to BizTalk Messaging Services. This lesson explains how to define your business processes, and how to apply them using BizTalk Orchestration Services.

BizTalk Orchestration Services enables you to create a detailed representation of your business process, and also to programmatically implement the business process within an integrated design environment based on Microsoft Visio 2002. Historically, the business-process design phase and the implementation phase were performed separately. One of the important features of BizTalk Orchestration Services is the integration of these previously distinct phases within a unified graphical design environment.

Because business processes are defined in a graphical environment, when these processes change at the business level the changes can be more rapidly reflected at the implementation level.

In addition to integrating design and implementation, BizTalk Orchestration Services provides the ability to create processes containing concurrency, the ability to do multiple tasks at the same time, and the ability to create robust, long-running business processes that span applications, platforms, and organizations.

To create robust, long-running business processes, BizTalk Orchestration Services saves instances of long-running business processes and suspends them, which conserves computing resources and provides extra reliability. At a later point, the server restarts these processes from the exact point at which they were suspended while waiting for a long operation to finish. Even if the computer was turned off in the interim, the suspended processes restart when triggered. An example of such a long-running operation could be waiting for payment of an invoice, an operation that usually takes 20 to 30 days before it is complete. For more information, see Understanding Orchestration Services.

Continue to Defining the Business Process.


Defining the Business Process

In this lesson you open and review the XLANG schedule drawing that represents Northwind Traders' business process for approving requisitions.

To review the Northwind Traders business process

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Orchestration Designer.

  2. On the File menu, click Open.

    The Open XLANG Schedule Drawing dialog box appears.

  3. Browse to C:\LearnBizTalk\Schedules, select NorthWindApprovalL3.skv, and click Open.

Note

  • You can close the blank drawing that appears in BizTalk Orchestration Designer.

The following illustration shows the Northwind Traders approval process drawing that was designed in BizTalk Orchestration Designer.

Northwind Traders approval process

If you have drawn diagrams using Microsoft Visio, the look and feel of BizTalk Orchestration Designer will probably be familiar to you. In BizTalk Orchestration Designer, you are defining your business process using flowchart shapes such as Action, Decision, and While instead of more complex items, such as documents, specifications, components, and messages. No limitations are imposed on the number or names of the steps in your business process. In addition, you can use Fork shapes to split the process into multiple concurrent paths, such as requesting the same price quote from multiple suppliers, and later reunite these paths with a Join shape. Finally, you can use the Transaction shape to bundle several steps of the process into a unitary transaction, if necessary. For more information, see Flowchart Shapes.

Continue to Implementing the Business Process.


Implementing the Business Process

Once the business process has been defined, you can implement it by configuring BizTalk Server to perform each of the tasks defined in the business process.

The following illustration shows the implementation shapes used in the Northwind Traders approval process.

Implementation shapes in BizTalk Orchestration Designer

You need to understand how to use the BizTalk Messaging shape, the COM Component shape, and the Message Queuing shape. Note that you do not write any code to bind the business processes together; your coding is in the individual components of specialized business logic, rather than the implementation that holds them together.

For example, by dragging and dropping the BizTalk Messaging shape onto the drawing, you open the BizTalk Messaging Binding Wizard, which walks you through a series of pages in which you define the messaging port that is associated with a given implementation shape. A messaging port is a collection of properties associated with a certain document destination, and your business process can be such a destination. For more information, see Implementation Shapes.

For simpler tasks, you can also create components in a scripting language of your choice, such as Microsoft® Visual Basic® Scripting Edition (VBScript). A component like this has been used in this XLANG schedule drawing. This script component exposes a method called DeclineReq, whose only job is to display a message box alerting the user that a requisition has been declined. For more information, see Creating a Script Component.

The NorthwindApprovalL3.skv XLANG schedule contains two script components and one BizTalk Messaging shape.

If a specific part of the business process requires you to perform specialized tasks, such as accessing internal databases or interfacing with a mainframe system, you would most likely implement them in a COM component and call the appropriate methods from BizTalk Orchestration Services.

The next lesson covers the process behind creating a script component.

Continue to Creating the Communication Flow.


Creating the Communication Flow

To create the communication flow you need to connect the business process definition with the implementation. Each flowchart shape used in the Flowchart stencil, as well as each implementation shape used in the Implementation stencil, has a control handle ( Control handle ) on its side. You connect an Action shape on the left with an Implementation shape on the right by drawing a line between the handle on the Action shape and the handle on the implementation port. After the shapes are connected, the XML Communication Wizard opens and prompts you to answer a few questions to determine how the communication between the shapes occurs. For more information, see Using the XML Communication Wizard.

After you connect the Action and Implementation shapes, the last step, on the Data page, is to define how the actual business document will be passed from one action to the next. You can view the Data page by clicking the Data tab at the bottom of the drawing in BizTalk Orchestration Designer. The next lesson contains more information about the Data page.

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To test the scenario

  1. Browse to C:\LearnBizTalk\Scripts and double-click L3Post.vbs.

    This script temporarily alters your XLANG schedule drawing so the requisition does not get passed to Contoso, Ltd yet. The original configuration will be restored later, but now it is useful to make this change so that you can see this step of the process.

  2. Copy the file ReqToDecline.xml from C:\LearnBizTalk\Documents into C:\LearnBizTalk\Pickup.

    The File receive function picks up that file and delivers it to BizTalk Messaging Services. BizTalk Messaging Services in turn invokes the Northwind Traders requisition approval process using BizTalk Orchestration Services, because you defined an XLANG schedule as the destination for the messaging port that was created for this business process. Finally, BizTalk Orchestration Services processes the requisition and displays a message box informing you that this particular requisition was declined.

  3. Repeat step 2 using the ReqToApprove.xml file.

    The message box informs you that the requisition has been approved.

Lesson 4 provides further information about configuring Implementation shapes in BizTalk Orchestration Designer, developing a script component, and what needs to be done on the Data page so your document is properly passed from action to action.

Continue to Lesson 4: Understanding Implementation.


Lesson 4: Understanding Implementation

In Lesson 4 you will extend the XLANG schedule from Lesson 3 and examine the implementation of the Northwind Traders' requisition-approval process.

Using BizTalk Orchestration Services, the requisition-approval process is implemented in the form of an XLANG schedule. In this lesson you will look at configuration parameters for various Implementation shapes, review the process involved in creating a Windows Script Component implementation, and learn what must be done on the Data page in BizTalk Orchestration Designer to ensure the correct flow of information in and out of an XLANG schedule.

The following topics are covered in this lesson:

  • Sending and Receiving Documents in BizTalk Orchestration Services

  • Adding Fields to Message Specifications

  • Working with COM Components

  • Creating a Script Component

  • Northwind Traders Data Page


Sending and Receiving Documents in BizTalk Orchestration Services

An XLANG schedule is the place where you implement your business process. In most cases, this process must examine the various fields of an incoming document and make decisions or perform actions based on the values. In this tutorial, the Total value of the Requisition document is checked and the requisition is approved only if its total is less than $1,000. Before this can happen, the Requisition document must first be delivered to the approval process.

To begin this lesson, open the NorthwindApproval.skv file in BizTalk Orchestration Designer. This file is very similar to the NorthwindApprovalL3.skv file in Lesson 3, except one of the Windows Script Components has been replaced by a BizTalk Messaging shape with the words Channel To Contoso written on it, as shown in the following illustration.

BizTalk Messaging shape Channel To Contoso

After the business process of the XLANG schedule drawing has been defined, and the implementations have been added, the diagram is compiled into an XLANG schedule. The schedule is a file written in the XLANG language, which is a language that uses various technologies to describe the logical sequencing of business processes, as well as the implementation of the business process. The XLANG language is expressed in XML. The XLANG schedule defines all the steps that must be performed, components that must be called, and data that must be passed to fulfill the defined process. After both sides of the diagram are completed, you can compile the XLANG schedule drawing by clicking Make XLANG <file name>.skx on the File menu in BizTalk Orchestration Designer.

In previous lessons you learned how to send a message containing a business document by using BizTalk Messaging Services. In this lesson you will combine the message and the business process.

In Lesson 2 you defined a messaging port and configured it to deliver the Requisition document to an XLANG schedule. You specified the name of an XLANG schedule (the XLANG file) that BizTalk Messaging Services should start to process the requisition. You also specified the name of a messaging port to receive the requisition within the schedule. This orchestration port must be configured inside BizTalk Orchestration Designer. Notice that the word "port" is used to refer to two different things; a messaging port defined in BizTalk Messaging Manager and an orchestration port defined in BizTalk Orchestration Designer are not the same thing.

Using a BizTalk Messaging implementation

The BizTalk Messaging shape is used to pass documents from BizTalk Messaging Services to BizTalk Orchestration Services.

When you add a BizTalk Messaging shape to the right-hand side of the XLANG schedule drawing, the BizTalk Messaging Binding Wizard opens. To edit an existing BizTalk Messaging implementation, double-click the BizTalk Messaging shape. In the BizTalk Messaging Binding Wizard, you name the orchestration port (this name must match the one you specified in BizTalk Messaging Manager), and also indicate whether this port receives documents or sends them, and whether it is used to start a business process.

If you need to send a document back to BizTalk Messaging Services, add a BizTalk Messaging shape to the right-hand side of the XLANG schedule drawing and specify the name of the channel to which the document must be sent. Note that this channel does not have to exist when you create your XLANG schedule drawing, but it must exist when the schedule is run.

After the orchestration port is created, connect the Action shape to the port and, in the XML Communication Wizard, specify whether the document is sent as XML or as a string, the message type information, and an optional XML specification to validate the document, similar to what you did earlier when you configured BizTalk Orchestration Services to receive documents from BizTalk Messaging Services. For more information, see Using the BizTalk Messaging Shape.

Using a Message Queuing implementation

Another way to receive a document in an XLANG schedule is to use the Message Queuing shape. When you add this shape to the drawing, the Message Queuing Binding Wizard starts and you are asked to specify a name of a private or public message queue that will be used to send or receive documents. However, if you choose to use Message Queuing to receive documents, the schedule does not start automatically, unlike when you receive documents from BizTalk Messaging Services. You must have another way to start the schedule after the document is posted on a queue.

When you connect the Receive Requisition action shape on the left side of the drawing to the ReceiveReq port, the XML Communication Wizard opens. To edit an existing Message Queuing implementation, and open the XML Communication Wizard, double-click the blue line that connects the Receive Requisition action with the ReceiveReq port.

The XML Communication Wizard prompts you to create a message that will be used to carry the document through the orchestration process represented by the XLANG schedule. More specifically, you are prompted to connect this message to other messages on the Data page, to specify whether the document is processed in XML format,and to specify a message type. You can optionally specify the name and location of an XML file, which contains your document specification, and BizTalk Orchestration Services can validate each document against this specification prior to processing it.

You can also send documents out of an XLANG schedule by using Message Queuing. In this case, instead of specifying the name of a channel, you need to specify the name of a private or public queue to which the document will be posted. For more information, see Using the Message Queuing Shape.

After the business process of the XLANG schedule drawing has been defined, and the implementations have been added, the diagram is compiled into an XLANG schedule. For more information, see Compile an XLANG schedule drawing into an XLANG schedule. The XLANG schedule defines all the steps that must be performed, components that must be called, and data that must be passed to fulfill the defined process.

Now that you know how to send and receive documents from BizTalk Messaging Services, let's look at what we can do with these documents within BizTalk Orchestration Services.

Continue to Adding Fields to Message Specifications.


Adding Fields to Message Specifications

Previously, you configured an XML communication for a message and indicated which XML specification represented the document being received. Now you can use BizTalk Orchestration Services to retrieve the values of individual fields inside the document and transfer the information to COM components or other messages.

  1. Open the XML Communication Wizard for the ReceiveReq port by double-clicking the blue line that connects the Receive Requisition action with the ReceiveReq port.

  2. Click Next four times.

    The Message Specification Information page of the wizard opens.

  3. In the Message fields area you will notice several entries. One of them, named Document, is the field that represents an entire document passed to the XLANG schedule. Click Add.

    The Field Selection dialog box appears.

    Because you specified that the documents passed into the XLANG schedule would match a specific XML specification, namely the Northwind Requisition specification, you can now select individual fields from this document by using a standard XML query language called XPath.

    Note

    • XPath is a language for addressing parts of an XML document and is a public standard maintained by the W3C. For more information about XPath, go to the XPath page on the W3C Web site (www.w3.org/TR/xpath.html).
  4. Expand the Items node and click totalPrice.

    An XPath for the node appears in the Node path box. The following illustration shows the Field Selection dialog box with the totalPrice field selected.

    Field Selection dialog box

    You can add other fields from the specification to your message in a similar way. All the fields added in this dialog box become available on the Data page in BizTalk Orchestration Designer, so you can use them in expressions and passed as parameters to components.

  5. Click Cancel to close the Field Selection dialog box.

  6. Click Cancel to close the XML Communication Wizard.

  7. On the left side of the XLANG schedule drawing, right-click the Decision shape and then click Properties.

    The Decision Properties dialog box appears.

  8. Click Edit.

    A dialog box similar to the following illustration appears.

    Rule Properties dialog box

    The Script expression shows that the value of the totalPrice field can be accessed by using the MessageName.FieldName notation. In this example, Message_1.totalPrice is used to get the Total Price value of the Requisition document.

Continue to Working with COM Components..


Working with COM Components

Now that you have the document inside the XLANG schedule, you can call various business components and pass your document as one of the parameters. These components can perform tasks, such as address business rules, access corporate databases and legacy systems, and send e-mail messages. The components can also modify the document itself and return these changes to the XLANG schedule to be passed on to the next action. To do this, you need to implement the business logic as standard COM components, add these components on the right side of the XLANG schedule drawing, and then choose which methods to call.

At this point in the tutorial, you have:

  • Read the Requisition document from a file on the hard disk and passed that file to BizTalk Messaging Services (using a File receive function).

  • Validated the Requisition document against an XML specification (by using a channel) and passed it to BizTalk Orchestration Services.

  • Received the document inside an XLANG schedule and retrieved the values of specific fields (using the XML Communication Wizard).

  • Used rule properties in a Decision shape to evaluate values and build your business logic.

The tutorial has not required any programming to build and implement a business process, so far. However, you might need to write a business component to implement certain company-specific actions (such as looking up requisition approval limits for certain members of your staff), so the following topic covers how to write a Windows Script Component. For more information, see Using the COM Component Shape.

Continue to Creating a Script Component.


Creating a Script Component

Microsoft Windows Script Components provide you with a way to create Component Object Model (COM) components by using scripting languages such as Microsoft Visual Basic Scripting Edition (VBScript) and Microsoft® JScript®. You can use script components just as any other COM components in any application that supports COM.

Script components perform differently from compiled components because they are interpreted at run time, but they are a way to prototype an interface for a COM component that will be developed later.

To give you a head start on the creation of script components, Microsoft has released the Windows Script Component Wizard. You can download this wizard from the MSDN Web site (msdn.microsoft.com/scripting/). Creating the skeleton code for your component is easy: choose a name for the component, decide which scripting language you will use to implement it, specify which properties and methods your component will have, and click Finish. The wizard generates all the code necessary for your component and saves it in a file with a .wsc extension. Then you can open the file in the editor of your choice and add the actual code behind your methods.

The component that you will use has two methods, ApproveReq and DeclineReq, and each method has a single parameter, document. The following illustration shows the page in the Windows Script Component Wizard where you add these methods to the script file.

Windows Script Component Wizard step 4 of 6

The following code is for the Requisition Approval component:

<?xml version="1.0"?>
<component>

<registration
   description="Req Approval"
   progid=" LearnBizTalk.ProcessReq"
   version="1.00"
   classid="{AD454A9F-58FE-4877-B7CD-F61BD45988F5}">
</registration>

<public>
   <method name="ApproveReq">
      <PARAMETER name="Document"/>
   </method>
   <method name="DeclineReq">
      <PARAMETER name="Document"/>
   </method>
</public>

<script language="VBScript">
<![CDATA[

function ApproveReq(Document)
MsgBox "Orchestration Engine Approved Requisition:" & vbCrLf & vbCrLf & Document, 64, "Requisition Approved"
end function

function DeclineReq(Document)
MsgBox "Orchestration Engine Declined Requisition:" & vbCrLf & vbCrLf & Document, 16, "Requisition Declined"
end function

]]>
</script>

</component>

Everything in this file, except for the implementation code of the ApproveReq and DeclineReq methods that are bold, was generated by the wizard.

Your business process flow might be complex, with COM components to be created by developers taking several weeks to write and test. This does not mean that you cannot design and test your XLANG schedule drawing before those components are finished. Use the Windows Script Component Wizard to create sample versions of your complex COM components, complete with the properties and methods they expose, and then use these script components in your XLANG schedule drawing in place of the actual COM components that will be completed later. You can now design your XLANG schedule drawing without having to wait for developers to finish coding. For more information, see Using the Script Component Shape.

You can also test BizTalk Messaging Services and BizTalk Orchestration Services integration with your script components and replace them with COM components developed in another language at a later time. When you are ready to replace the script components, you add a COM Component shape to the XLANG schedule drawing. This opens the COM Component Binding Wizard, which prompts you for information to create a new orchestration port. Then you disconnect your existing Action shape that was previously attached to a script component port implementation, reconnect it to the new orchestration port, and recompile the schedule.

Continue to Northwind Traders Data Page.


Northwind Traders Data Page

After an XLANG schedule drawing has been drawn, and all the Implementation shapes have been connected to their Action counterparts, you need to configure the flow from one step of the process to the next using a Data page in BizTalk Orchestration Services. Before you complete the Data page, it looks similar to the following illustration.

Northwind Traders Data page

Note that the Data page shows several groups of fields, each group named after the message that carries the document to or from an orchestration port.

Open NorthwindApproval.skv in BizTalk Orchestration Designer and click Data Page on the View menu. Notice how the Document field in Message_1 has been connected to the Document field in Message_2 and DeclineReq_in. This indicates that the document received from BizTalk Messaging Services by Message_1 is passed to the DeclineReq_in message, which is the message that will submit the document to the script component, as well as to Message_2, which will send the same document back to BizTalk Messaging Services. You can rearrange the messages on this page to make the drawing easier to understand.

To view the data page click the Data tab at the bottom of the design pages. The Data page in NorthwindApproval.skv should look similar to the following illustration.

Northwind Traders Data page with connections

After the flow of data between messages is defined, you can compile the drawing into an executable XLANG schedule.

To save and compile an XLANG schedule drawing

  1. On the File menu, click Save <file name>.skv.

  2. On the File menu, click Make <file name>.skx.

    The Save XLANG Schedule to dialog box appears.

  3. Verify the location where the XLANG schedule will be saved and click Save.

  4. On the File menu, click Exit to close BizTalk Orchestration Designer.

    Your XLANG schedule is now ready to be run.

For more information, see Compiling XLANG schedules.

The next lesson covers preparing the document for delivery to the trading partner by transforming it with the use of maps, and explains how to use these maps with BizTalk Messaging Services.

Continue to Lesson 5: Using BizTalk Mapper.


Lesson 5: Using BizTalk Mapper

In the previous lessons you learned how Microsoft BizTalk Server 2002 accepts documents from line-of-business applications, and how these documents are processed within BizTalk Orchestration Services.

In this lesson you will see how the Requisition document is prepared for submission to Contoso, Ltd and go through the steps within BizTalk Messaging Services to accomplish this task.

The following topics are covered in this lesson:

  • Creating the Map

  • Using the Map

  • Running the Scenario


Creating the Map

The Requisition document you have been using so far represents an internal purchase requisition produced by an application at Northwind Traders. When this requisition is approved by a business process (implemented in this scenario by using BizTalk Orchestration Services), a purchase order (PO) must be sent to Contoso to actually buy the merchandise.

At this point, there is no PO document, only a requisition. However, the structure of Contoso's PO, and most of the data required to create the PO document, such as the list of items and the billing address, is actually contained within the requisition. To transform the information contained in the Requisition document into a PO that Contoso, Ltd can use, you use BizTalk Mapper. BizTalk Mapper uses an Internet standard called XSL Transformations (XSLT), which is a language for transforming XML documents from one XML schema into another.

Note

  • XSLT is a W3C recommendation. For more information about XSLT, go to the XLST page on the W3C Web site (www.w3.org/TR/xslt.html).

You do not need to know anything about XSLT to use BizTalk Mapper. BizTalk Mapper is a highly graphical tool that presents you with both specifications side-by-side and lets you define transformations by simply drawing lines between the specification fields. For more information, see Mapping Specifications.

For those cases when simple rules, such as Field A from Document 1 is mirrored into Field B in Document 2, are not enough, BizTalk Mapper offers a series of powerful transformation elements called functoids. There are over 60 functoids included with BizTalk Mapper, enabling you to perform mathematical, logical, string, date/time, scientific, database, and other operations. There is also a script functoid that enables you to write your own subroutines in Microsoft Visual Basic Scripting Edition (VBScript), in case none of the existing functoids are suited for the operation. The resulting VBScript code is embedded directly into the XSLT generated by BizTalk Mapper. For more information, see Understanding Functoids.

Note

  • You can do even more powerful things by cascading functoids, which is a method of passing the results of one functoid execution as input to the next functoid. You can also create custom functoids in a language such as Visual Basic and add them to your functoid palette for future use.

For this business scenario we built a map that translates Northwind Traders' Requisition document into Contoso's PO. This map is stored in the file ContosoPOMap.xml located in the C:\LearnBizTalk\Documents\ directory. By opening this map in BizTalk Mapper, you will see the screen shown in the following illustration.

ContosoPOMap.xml opened in BizTalk Mapper

Most of the fields required to build the PO document for Contoso were already present in the Requisition document, perhaps under different names. Some of the fields, such as PO Number, are new, and therefore their values had to be generated.

You can see that we used three functoids in this map:

  • A string concatenation functoid that combines two address fields in the requisition into one field in the PO

  • A date/time functoid that generates the current timestamp for the created field

  • A script functoid that implements a specific business rule to generate a PO number (In this example, the functoid picked a random number for the PO number.)

Because the values of some destination fields do not change over time (for example, the name and address of your company), BizTalk Mapper enables you to specify constant values to be used. To do this, highlight the field for which you need to provide a constant value, click the Values tab, and enter your value. The following illustration shows the Values tab.

Values tab in BizTalk Mapper

Note

  • You cannot link to a node in a destination specification that has a destination constant value associated with it.

For more information about how to create a map, see Module 2 in the BizTalk Server 2002 Tutorial.

Continue to Using the Map.


Using the Map

Now that we have created the map, let's go back to BizTalk Messaging Manager and configure the channel called Channel To Contoso, which is used to deliver the PO to Contoso, Ltd while using the map.

This is the same channel that you specified in the XLANG schedule drawing described in Lesson 4 when you configured the port that delivered the Requisition document to Contoso, Ltd. Note that the XLANG schedule outputs the same Requisition document as it receives, and it does not detect any potential transformations to this document (such as translation into a PO) that occur later in BizTalk Messaging Services. This separation between a business process used for the requisition approval and the technical details behind managing document format and delivery mechanism is what makes the overall solution so flexible and easily adaptable.

The key point here is that BizTalk Orchestration Services is the technology for creating business processes, while BizTalk Messaging Services is the technology for reliably sending documents between business processes to integrate them.

In the future, if Contoso, Ltd decides to change the format of its POs, you will be required to update only your specification for Contoso PO and update the map to reflect the new specification changes, rather than recreate the entire business process.

When you configure the channel in BizTalk Messaging Manager, if you specify an outbound document definition that is different from an inbound one, BizTalk Messaging Manager will automatically prompt you to provide a map document to translate between these two document specifications. The following illustration shows where the map document is identified.

Outbound Document page in the Channel Properties Wizard

To open the channel to Contoso and view the channel properties:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. In the Search for other items area, click Channels.

  4. Click Search Now.

In the Channel Name list, double-click Channel to Contoso.

  5. Click Next three times to get to the Outbound Document page.

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To run the scenario

  1. Browse to C:\LearnBizTalk\Scripts\ and double-click L5Post.vbs.

    This script removes the temporary changes we made to the orchestration process at the end of Lesson 3 and enables BizTalk Orchestration Services to output the document to BizTalk Messaging Services.

  2. Copy the file ReqToDecline.xml from C:\LearnBizTalk\Documents\ to the C:\LearnBizTalk\Pickup\ directory.

    As before, this requisition gets declined and you receive the message box informing you of this.

  3. Repeat step 2 using the ReqToApprove.xml file instead.

    This requisition gets approved and BizTalk Orchestration Services sends it to BizTalk Messaging Services.

    The channel receives the document, converts it into Contoso's PO by applying the map you specified, and BizTalk Messaging Services writes the resulting document under the name ContosoPO.xml to the C:\LearnBizTalk\Output\ directory.

    Note

    • You will not receive a message box indicating that the requisition has been approved when this message is written to a file.
  4. Browse to C:\LearnBizTalk\Output\ and double-click ContosoPO.xml to open it in Microsoft Internet Explorer.

    Look at the values of the PO Number field that was randomly generated by the script functoid, the created field that contains the time when this file was generated, and the address field that contains the values from both original addr1 and addr2 fields concatenated by the string functoid.

For more step-by-step procedural information about how to use BizTalk Mapper, see Module 2 of the BizTalk Server 2002 Tutorial.

In the next lesson you will learn about some different ways to deliver documents to your business partners and how standard Internet protocols once again help to make this job easier.

Continue to Lesson 6: Sending and Receiving Documents.


Lesson 6: Sending and Receiving Documents

In this lesson you will learn about the process Northwind Traders uses to send the purchase order (PO) to Contoso, Ltd, and how this order is received and stored by Contoso.

The following topics are covered in this lesson:

  • Choosing a Protocol

  • Receiving Documents over HTTP

  • Using the Queue

  • Running the Scenario


Choosing a Protocol

After the purchase order (PO) document is generated, it must be submitted to Contoso, Ltd for processing. When choosing a transport service for this task, you must consider several important characteristics:

  • The transport service must use a standard protocol — you want to know that your trading partner (Contoso) can receive documents using a variety of software running on any platform.

  • The transport service must be reliable — you want to be sure that the document was indeed received by the trading partner on the other side.

  • The transport service must be secure — you want to know that you can encrypt the entire transmission process to protect sensitive data.

For this scenario we chose a transport service that uses Hypertext Transfer Protocol (HTTP). HTTP is a standard protocol used by Internet browsers to retrieve information from Web servers. Most administrators of corporate firewalls feel comfortable with allowing transmissions based on HTTP to be sent outside the company. This is an important aspect of the process involving choosing the right transport service. Your server running Microsoft BizTalk Server needs to communicate with internal applications, databases, and legacy systems; therefore it must be located within the firewall. At the same time, it might need to send and receive documents from an outside partner, preferably using a well-known protocol that can go through the firewall.

HTTP is reliable from a transport perspective because it defines a standard way for the receiving side to communicate the status of the transmission back to the sender. From a business process perspective you want to be able to recover when temporary Internet glitches cause a transmission failure. BizTalk Server can monitor the transmission process, retry sending documents for a pre-configured number of times, and alert an administrator if transmission was unsuccessful.

Finally, HTTP has a secure variation, Secure Hypertext Transfer Protocol (HTTPS), which enables encryption of the entire transmission by using standard algorithms. HTTPS encrypts the entire communication stream with a trading partner, and it can be used in conjunction with encrypting and digitally signing the document to provide an extra level of security.

Note

  • An alternative way of sending documents to trading partners could be by using the File transport service to save a document into a file on a hard disk and then have another process pick up these files and deliver them to a partner by using an EDI-VAN dialer or an FTP process.

For more information about the transport services that BizTalk Server 2002 supports, see Transport Services.

Continue to Receiving Documents over HTTP.


Receiving Documents over HTTP

Now let's look at what must be done by the receiving side to accept a document that was transmitted by BizTalk Server using HTTP, and to process it. For this scenario we will assume that Contoso, Ltd also uses BizTalk Server to receive POs and to generate and send invoices.

Because BizTalk Server is running on Microsoft Windows 2000 Server, a platform that includes Internet Information Services (IIS) 5.0, Contoso can use an Active Server Pages (ASP) script to accept documents from BizTalk Server on the Northwind Traders side and submit them for processing to BizTalk Server on the Contoso, Ltd side.

Note

  • In these lessons we use a single instance of BizTalk Server to simulate processing for both Northwind Traders and Contoso, Ltd. In a real production environment these would be separate servers running at the sites of each respective company.

After an ASP script receives the document, it must eventually send it back to BizTalk Server for further processing. While there are several options available to achieve this, we would like to emphasize the importance of designing a solution that can achieve this result in a fail-safe way.

For example, if Contoso's servers are temporarily down for scheduled maintenance or an upgrade, or if Contoso is experiencing an unusually high load on its servers, and the processing of POs cannot be done in real time, this should not affect Northwind Traders' or any other trading partner's ability to submit PO documents. In fact, Northwind Traders should be completely unaware of anything happening on Contoso's side or of the technology being used, except that the PO can be transmitted successfully. Therefore, although BizTalk Server provides a standard way to accept documents using COM, it is not the best approach in this particular example.

Let's look at a better way to architect this part of a solution. Once the ASP script receives the transmitted document, it should store the document to a file on a hard disk, and then exit indicating that the document was successfully received. Meanwhile, BizTalk Server can retrieve the stored document and process it in a completely asynchronous manner. In Lesson 2 you learned about File receive functions in BizTalk Messaging Services and how to use them to post a file to a specific location that BizTalk Server is monitoring. Therefore, it is possible in this scenario for the ASP script to store a document into a file, which is later picked up by a File receive function. Such architecture provides flexibility in deciding exactly when BizTalk Server processes the documents, and in adding more BizTalk Servers to process incoming documents as business needs increase.

The following topic presents an alternative way of achieving the same reliable results without storing documents in files and includes the added benefit of being transactional.

Continue to Using the Queue.


Using the Queue

Message Queuing (also known as MSMQ) is one of the standard components of Windows 2000 Server, and it provides another simple and reliable way to build an asynchronous solution just like the one we are designing.

After the document is received by an ASP script, instead of storing it into a file on a hard disk, you can post the document as a message in a message queue on the server, and then deliver it to BizTalk Messaging Services by using a Message Queuing receive function, which works similarly to a File receive function. In most configurations Message Queuing can be set up as transactional for enhanced reliability.

The overall process is shown in the following illustration.

Lesson 6 process overview

To create a new Message Queuing receive function

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand BizTalk Server Group, right-click Receive Functions, point to New, and then click Message Queuing Receive Function.

    The Add a Message Queuing Receive Function dialog box appears.

  3. In the Name box, type a name for your function and, in the Polling location box, type the queue name for the polling location.

  4. Click Advanced.

    The Advanced Receive Function Options dialog box appears.

  5. In the Channel name box, select the channel from the drop-down list that will process documents received by this function.

    Notes

    • If you are using a private message queue to store documents, enter the queue name using the following format: DIRECT=OS:.\private$\<queue_name>.

    • If you are using a public queue, enter the queue name in the following format: DIRECT=OS:<server_name>\<queue_name>.

You can look at the properties of the ReceivePO Message Queuing receive function that was configured during setup. This receive function will process PO documents accepted by the ASP script discussed previously. This function has been temporarily suspended, so the documents will remain on the queue, which enables you to examine them. You can re-enable this function at the end of this lesson.

Next we review the script inside the ContosoReceive.asp file to see the series of steps performed to accept the data transmitted by BizTalk Server and to post it to a message queue. This code begins by using a BinaryRead method of a Request object provided by ASP to read all the transmitted data. Next, Microsoft® ActiveX® Data Objects (ADO) is used to transform the received data from binary format to text format. Finally, Message Queuing functions are used to create a new queue message and post it to a private queue that we choose.

You can see the entire source code inside the ContosoReceive.asp file located in the C:\LearnBizTalk\ASP\ directory.

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To run the scenario

  1. Browse to C:\LearnBizTalk\Scripts\ and double-click L6Post.vbs.

    This script will restore the configuration of the messaging port Port To Contoso that was modified previously and instruct it to deliver documents to Contoso, Ltd using an HTTP transport, rather than writing it to a file as was done in Lesson 5.

  2. Copy the file ReqToApprove.xml from C:\LearnBizTalk\Documents into the C:\LearnBizTalk\Pickup\ directory.

    The file is processed by a File receive function, passed from BizTalk Messaging Services to BizTalk Orchestration Services for approval, then delivered back to BizTalk Messaging Services, and finally transmitted to Contoso by using the HTTP protocol.

An ASP script simulating the Contoso, Ltd side reads the transmitted data, converts it back into a document, and posts the document to a local private queue.

Afterward, a Message Queuing receive function should retrieve the document off the queue and submit it to BizTalk Messaging Services; however, as you might recall we temporarily disabled this receive function so you can examine the document posted to the queue.

To see the messages on the queue

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Computer Management.

    The Computer Management console appears.

  4. In the Computer Management console tree, expand Services and Applications, expand Message Queuing, expand Private Queues, and then expand ContosoPOQueue.

  5. Click Queue Messages in the left pane to show all the messages currently posted to the queue.

  6. Right-click the message in the right pane, click Properties, and then click the Body tab to see the beginning of the message body.

After you examine the message, delete it from the queue by right-clicking Queue Messages in the left pane, and then clicking All Tasks and Purge.

For more information, see Understanding Receive Functions and Document Routing.

In the next lesson we will discuss the final steps of the scenario, namely processing of the Purchase Order document by Contoso, generating the Invoice, and delivering it to Northwind Traders.

Continue to Lesson 7: Completing the Transaction.


Lesson 7: Completing the Transaction

In Lesson 7 we will learn how Contoso, Ltd receives the PO sent by Northwind Traders over the Internet, processes this order using BizTalk Messaging Services and BizTalk Orchestration Services, generates the invoice, and sends it back to Northwind Traders. Finally, we will review how Northwind Traders receives the invoice and stores it, thus completing this example of buyer-supplier communications.

The following illustration shows the remaining parts of the scenario.

Lesson 7 process overview

The following topics are covered in this lesson:

  • Message Queuing

  • Processing the Order

  • Running the Scenario


Message Queuing

Lesson 6 ended when a PO document received by an ASP script on the Contoso, Ltd side was delivered to a message queue. You also learned about configuring a Message Queuing receive function, which monitors the message queue for any incoming messages and delivers them to BizTalk Orchestration Services. We chose to store incoming POs on a message queue, rather than storing them in files, because a message queue offers an additional level of reliability by supporting transactions, a feature not found in a file system.

After the Message Queuing receive function takes the document off the queue, it submits the document to the channel, which in turn delivers it to the messaging port you created for Contoso's business process. This messaging port is configured to transport the document to an XLANG schedule, indicating that it will start an XLANG schedule to run Contoso's business process in a manner similar to the Requisition document that was submitted to Northwind Traders' XLANG schedule in Lesson 4.

Continue to Processing the Order.


Processing the Order

The actual work that has to be completed to process a real PO varies from one company to the next. To simplify this scenario, we defined a single Action shape (Do Some Work) within Contoso's XLANG schedule drawing, which represented all of the actions that would normally be performed by a real-world supplier, such as checking inventory levels and communicating shipping instructions to the warehouse.

The implementation for the Action shape is a simple Windows Script Component, ProcessPO.wsc, that displays a message box, which advises the user that a PO is being processed. We used the Windows Script Component Wizard to assist in the creation of this component.

Of course, in a production system no message boxes should be displayed by any BizTalk Orchestration Services components, for the simple reason that there will not be a user currently logged on at the server to observe and acknowledge these messages. Until a user dismisses the message box, the schedule will not continue to run, potentially causing unwanted effects. A more appropriate means of communication is by sending e-mail messages, or by writing Windows Event Log entries that can in turn trigger other actions.

To open Contoso's XLANG schedule drawing, browse to C:\LearnBizTalk\Schedules\ and double-click ContosoInvoice.skv. The following illustration shows the BizTalk Orchestration Services process for Contoso, Ltd as defined in the XLANG schedule drawing.

BizTalk Orchestration Services process for Contoso, Ltd

In this XLANG schedule drawing, we used the XML Communication Wizard to extract individual values of fields, in this case the PONumber and Generated fields, from the PO document and pass them to the script component as parameters, without having to write any code. This is similar to the way we extracted the value of the RequisitionTotal field from the Requisition document in Lesson 4.

On the Data page of the XLANG schedule drawing, we connected these fields to input parameters of the DoWork method of the script component. As you can see from the following illustration, the entire PO is not passed to the component, just the two individual fields that we extracted.

ContosoInvoice Data page

When you run this scenario and click OK on the message box presented by the script component, the XLANG schedule sends the PO back to BizTalk Messaging Services, where it is transformed into an invoice by using another map, and then sent to Northwind Traders by using the HTTP transport — the same transport Northwind Traders used to send POs to Contoso, Ltd.

Once an ASP script on the Northwind Traders' side receives the invoice document, it stores the invoice as a file for further processing. In a real-world scenario such processing can include matching the invoice with the original requisition and PO, updating internal systems with invoice information, and so on.

Continue to Running the Scenario.


Running the Scenario

Important

  • To successfully run this scenario you must copy the LearnBizTalk directory to your C drive and all the BizTalk Server components must be installed on drive C. Although it is possible to run these files from another drive and directory, you would need to make extensive modifications to the source files. For more information about these requirements, see Learning BizTalk Server 2002.

To run the scenario:

  1. Browse to C:\LearnBizTalk\Scripts\ and double-click L7Post.vbs.

    This script will re-enable the Message Queuing receive function that was temporarily suspended in Lesson 6.

  2. Copy the requisition document, ReqToApprove.xml, from the C:\LearnBizTalk\Documents directory and paste it into the C:\LearnBizTalk\Pickup directory.

The following is an outline of the complete flow for this scenario:

  1. The File receive function at Northwind Traders reads the file 'ReqToApprove.xml' that was placed in a \Pickup directory and sends it to the Northwind Traders BizTalk Orchestration Services process by using BizTalk Messaging Services.

  2. The XLANG schedule extracts the value of the RequisitionTotal field and, because it is less than $1,000, approves the requisition by sending it back to BizTalk Messaging Services.

  3. BizTalk Messaging Services receives the requisition from BizTalk Orchestration Services, and uses a map to create a PO document. This document is then transmitted to Contoso, Ltd using the industry-standard HTTP protocol.

  4. An ASP script on the Contoso, Ltd side receives the transmission, extracts the document, and posts it as a message to a private message queue.

  5. A Message Queuing receive function finds a new document on the queue, retrieves it, and uses BizTalk Messaging Services to send it to BizTalk Orchestration Services for processing.

  6. The XLANG schedule extracts the values of the PONumber and Generated fields and invokes a method on a script component, displaying a message box that indicates the arrival of the PO.

  7. The XLANG schedule sends the PO back to BizTalk Messaging Services for invoice generation.

  8. BizTalk Messaging Services applies a map to turn the PO into an invoice and transmits it to Northwind Traders by using the HTTP protocol.

  9. An ASP script at Northwind Traders accepts the transmission, extracts the document, and saves it as the file C:\LearnBizTalk\Output\ContosoInvoice.xml.

This completes the process of integrating the internal business processes and applications between the two sample businesses, Northwind Traders and Contoso, Ltd. The following illustration shows the components of this process, including the two XLANG schedules, BizTalk Messaging Services, receive functions, ASP pages, and queues, and their relationships.

Complete process overview

If you now open the C:\LearnBizTalk\Output directory, you will find a file named ContosoInvoice.xml containing the invoice that Northwind Traders received from Contoso, Ltd and stored in this file.

Continue to the Conclusion.


Conclusion

Over the course of these seven lessons you have witnessed the creation of a fully functional, integration scenario between a buyer and a supplier.

We hope these lessons have helped you to better understand Microsoft BizTalk Server, and to learn how BizTalk Server can significantly reduce the amount of work required to integrate business-to-business processes.

To undo the configuration changes made to your BizTalk Server installation by the scripts you ran during these lessons, run the Cleanup.vbs script located in the C:\LearnBizTalk\Scripts\ directory. After the script completes, which is indicated by a message box, you can safely remove the C:\LearnBizTalk directory and all the files it contains.

For a step-by-step tutorial of how to configure BizTalk Server processes, see the BizTalk Server 2002 Tutorial. The BizTalk Server Tutorial will help you better understand how to use BizTalk Editor, BizTalk Mapper, BizTalk Messaging Manager, BizTalk Server Administration, and BizTalk Orchestration Designer to configure BizTalk Server to run a business-to-business automated procurement process.

To learn more about BizTalk Server 2002, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk). This Web site contains technical product information, white papers, training and events, and third-party offerings.


E-Procurement Sample

This sample highlights the following new features of Microsoft® BizTalk™ Server 2002:

  • BizTalk SEED Wizard—rapid partner enabler

  • Application Center 2000 deployment

  • Advanced monitoring capabilities using Microsoft Operations Manager (MOM)

  • New XLANG correlation using common queues instead of per-instance queues

  • HTTP receive function

In this scenario we look at a business situation where your company is purchasing products from several different suppliers. We focus on setting up a business solution, using Microsoft BizTalk Server 2002, the Internet, and correlation, that automates the procurement process that takes place between your company and its suppliers. We call this solution e-procurement.

In this scenario you set up a hub for your company. The hub handles all the purchase order, invoice, and payment documents that are sent back and forth to and from the suppliers. The EprocSetup application that is included with this sample configures the hub and one supplier system to use BizTalk Server, the Internet, and correlation to handle these documents and complete the procurement process. After the configuration is complete you run the DocumentGenerator.vbs script to start a transaction in which a purchase order is sent to the supplier, an invoice is returned from the supplier, and the hub sends a payment. Finally the supplier sends a payment acknowledgement and the e-procurement process is complete. The following illustration shows the business transaction used in this sample.

Data flow in a business transaction

After the e-procurement sample is running successfully we focus on how to deploy this configuration to other servers by using Microsoft Application Center 2000, so that this configuration is taken from a test environment to a production environment. We also explain how to package the supplier's configuration by using the BizTalk SEED Wizard so that it can be easily picked up from your Web site and implemented by other suppliers. Finally we cover how you can set up Microsoft Operations Manager (MOM) to monitor the activities taking place in the hub.

The following topics cover the setup and configurations that are necessary to work through this scenario:

  • User's Guide
    • Preliminary Setup

    • Running the E-Procurement Sample
  • Programming Notes

  • Optional Monitoring and Deployment Procedures
    • Using Application Center for E-Procurement Deployment

    • Creating a SEED Package

    • Creating a MOM Custom Counter for the E-Procurement Sample


User's Guide

Before you run this sample you must attach the correlation databases and run the e-procurement setup program.

Important

  • The instructions in this sample assume that this sample and BizTalk Server 2002 are installed on the same drive.

  • The eProcurement sample files must be copied to a folder named eProcurementSample on the root level of the drive. These sample files are located on the root level of the BizTalk Server 2002 CD in the eProcurementSample folder.

  • After copying the files to your drive, verify that the empty folder PaymentAckReceived exists directly under the ePprocurementSample folder. Create the PaymentAckReceived folder if it does not exist.

To prepare and run the e-procurement sample, complete the following procedures:

  • Preliminary Setup

  • Run the E-Procurement Sample


Preliminary Setup

The steps in this section explain how to configure your system to run the e-procurement sample. Before you can run the e-procurement sample you must attach correlation databases and configure the hub and supplier systems. In this scenario, both the hub and the supplier are configured on one BizTalk Server installation. In an actual production environment the hub and the supplier would be two totally separate entities.

Prerequisite

This sample assumes that you have the following installed on the computer that is running BizTalk Server:

  • Microsoft BizTalk Server 2002

  • Microsoft SQL Server™

  • Message Queuing (also known as MSMQ)

Note

  • If you plan to continue to the Application Center section of this demo, you need to install Application Center before you install BizTalk Server.

  • It is also recommended that you run the sample on a clean installation of BizTalk Server. If you would like to quickly delete all the BizTalk Server objects (ports, channels, and so on), you can run the CleanBTM.vbs script that is located in the eProcurementSample directory.

Important

  • The script CleanBTM.vbs removes all configuration information from the BizTalk Messaging Management database. This script should only be run in a testing environment.

Attach the databases

In this procedure you set up the correlation databases that are used with the e-procurement sample using Microsoft SQL Server 2000. If you are using Microsoft SQL Server 7.0, see the "Create the databases" section. There are two correlation databases, one for the hub and one for the supplier. These databases capture and hold the globally unique identifier (GUID) and TransactionID that are generated when the XLANG schedule begins. The GUID and the TransactionID are used to correlate the documents that are sent and received throughout this transaction to the correct XLANG schedule. The TransactionID is an identifier such as a purchase order number or invoice number.

Note

The following instructions assume that SQL Server 2000 is installed on the same computer as BizTalk Server. If SQL Server is installed on a different computer, you will need to modify these instructions so that they will work in your environment. Before you begin this procedure, verify that the properties on the CustomCorrelation_Data and SupplierCustomCorrelation_Data databases are not set to read-only. The database files are in the Databases directory, located in the eProcurementSample directory.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

    The SQL Server Enterprise Manager appears.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which you want to attach the database.

  3. Click Databases.

  4. On the Action menu, point to All Tasks and click Attach Database.

    The Attach Database dialog box appears.

  5. Click the browse button (…).

    The Browse For Existing File dialog box appears.

  6. Browse to the Databases directory, located in the eProcurementSample directory.

  7. Click CustomCorrelation_Data.MDF, and then click OK.

    A message box appears indicating that the process was successful.

  8. Repeat the steps in this procedure to attach the file SupplierCustomCorrelation_Data.MDF located in the Databases directory, located in the eProcurementSample directory.

Create the databases

The following procedure should be used if you are using Microsoft SQL Server 7.0 in your BizTalk Server installation.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server 7.0, and then click Enterprise Manager.

    The SQL Server Enterprise Manager appears.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which you want to attach the database.

  3. Click Databases.

  4. On the Action menu, click New Database…

    The Database Properties menu appears.

  5. In the Name field, type CustomCorrelation as the name of the database.

  6. Click OK.

  7. On the Action menu, click New Database…

  8. The Database Properties menu appears.

  9. In the Name field, type SupplierCustomCorrelation as the name of the database.

  10. Click OK.

  11. Close the SQL Server Enterprise Manager.

  12. On the Start menu, point to Programs, point to Microsoft SQL Server 7.0, and then click Query Analyzer.

    The Connect to SQL Server menu appears.

  13. Make sure that the correct information to connect to SQL Server is entered. Click OK.

  14. On the menu bar, make sure that the value in the DB field is CustomCorrelation. If it is not, click the DB drop-down list box and select CustomCorrelation.

  15. On the File menu, click Open.

  16. Browse to the Databases directory, located in the eProcurementSample directory.

  17. Click the CustomCorrelationTable.sql file.

  18. On the Query menu, click Execute. This will process the CustomCorrelationTable.sql file. If the SQL file has been run, you will see a message stating: The command(s) completed successfully.

  19. Repeat the steps in this procedure for the SupplierCustomCorrelationTable.sql file.

  20. Close Query Manager.

Set up the e-procurement configuration

In this procedure you run the setup application to configure the BizTalk Server for the hub and the supplier to run the e-procurement sample.

The e-procurement setup application performs the following tasks:

  • Creates these message queues:

    .\private$\receiveinvoice

    .\private$\receivepayment

    .\private$\receivepaymentack

    .\private$\receivepo

    .\private$\receivepo2

    .\private$\supplierreceivepo

    .\private$\supplierreceivepo2

    The queues are used to transfer data between the business partners represented by the running hub and supplier XLANG schedules.

  • Creates the virtual directories

    The virtual directories work with HTTP receive functions to enable a trading partner to submit data to BizTalk Server.

    When complete, your virtual directory structure should look similar to the following:

    Alias | Web site structure | Directory path
    hub | Hub | \Program Files\Microsoft BizTalk Server\HTTP Receive
    paymentack | hub/paymentack | \Program Files\Microsoft BizTalk Server\HTTP Receive
    supplier | Supplier | \Program Files\Microsoft BizTalk Server\HTTP Receive
    payment | supplier/payment | \Program Files\Microsoft BizTalk Server\HTTP Receive

    Note

    • The virtual directory Application Protection value is set to Low (IIS Process) for all virtual directories used by this sample. Medium (Pooled) is the default value.
  • Creates the channels and ports

    Each channel is configured to override the messaging port default values and associate the message with a specific XLANG schedule instance by using the message label.

  • Registers the COM components

  • Moves the document specifications to the WebDAV folder

  • Creates the HTTP receive functions

  • Configures the BizTalk Messaging Management database

  • Registers the necessary DLLs

Prior to running the setup application, verify that none of the message queues listed above exist. If any of these queues exist, the e-procurement sample setup might fail.

To set up the e-procurement sample:

  1. In Windows® Explorer, browse to the \COM Components\Setup directory located in the eProcurementSample directory.

  2. Double-click eProcSetup.exe.

    A setup dialog box appears.

  3. Click eProcurement Setup.

    A dialog box appears indicating that the setup was successful.

Continue to Run the E-Procurement Sample.


Run the E-Procurement Sample

The e-procurement sample demonstrates how to correlate user-defined fields in an XLANG schedule. This allows you to use a data value that uniquely identifies a document, such as a purchase order number, and associate that identifier with a running XLANG schedule instance to process a document through the steps of a business transaction.

To run this sample, follow these steps:

  1. In Windows Explorer, browse to the eProcurementSample directory.

  2. Start the XLANG Event Monitor located in \Program Files\Microsoft BizTalk Server\SDK\XLANG Tools.

  3. Double-click DocumentGenerator.vbs.

To verify that the transaction was completed successfully, browse to the PaymentAckReceived directory located in the eProcurementSample directory. This directory should contain a payment acknowledgement XML file that uses the following naming convention: payack_[GUID].xml.

To run the sample and have the purchase order denied on the hub, change the POTotal in PO.xml to a value greater than 1000. To run the sample and have the purchase order denied by the supplier system, change the POTotal in PO.xml to a value less than 300. The PO.xml file is located in the eProcurementSample directory.

Note

  • By default, the hub and supplier schedules are bound to the Windows Scripting Component located at C:\EprocurementSample\Script Components\Message.wsc. If the component does not exist at this location, the schedule will fail. To resolve this issue, open the schedules in BizTalk Orchestration Designer and use the Script Component Binding Wizard to rebind the script file to the correct drive and path for the component.

Continue to Programming Notes.


Programming Notes

E-procurement XLANG schedule activation

When you run this sample, PO.xml is dropped in the ReceivePO queue, an XLANG schedule is activated, and the e-procurement process begins. The HubReceivePO messaging port activates a new instance of the XLANG schedule hub.skx, and then delivers the document to the ReceivePO port. After the purchase order is approved it is sent to the hub. The hub sends the purchase order to the supplier and waits to receive an invoice.

The HTTP receive function is used to deliver the purchase order to the supplier. After the supplier receives the purchase order, an XLANG schedule is activated on the supplier system and the process begins on that system. The SupplierReceivePO messaging port activates a new instance of the XLANG schedule supplier.skx, and then delivers the document to the ReceivePOfromHub port. When the purchase order has been transformed to an invoice it is sent back to the hub.

The HTTP receive function is used to deliver the invoice to the hub. The hub receives the invoice and sends a payment. Again, the HTTP receive function is used to deliver the payment to the supplier. When the supplier receives the payment it sends an acknowledgement. The transaction is complete when the acknowledgement is received by the hub and written to a file at \eProcurementSample\PaymentAckReceived.

E-Procurement XLANG schedule correlation

Every instance of an XLANG schedule is assigned a GUID by the XLANG Scheduler Engine. In this sample the GUID is extracted from the message, stored in a correlation database, and associated with a TransactionID such as a purchase order number or invoice number.

More specifically, when the hub receives a purchase order the GUID is extracted, stored in the CustomCorrelation database, and associated with a TransactionID. When the supplier receives the purchase order it sees that TransactionID, but also generates a GUID and TransactionID of its own to be stored in the SupplierCustomCorrelation database. These values are used to correlate incoming and outgoing messages to the correct running schedule instance as the transaction goes from purchase order to invoice, from invoice to payment, and completes at the payment acknowledgement. The correlation actually begins when the hub receives an invoice and the invoice has to be associated with the correct purchase order and thus the correct XLANG schedule.

For additional information about correlation, see:

XLANG Schedule Correlation

Instance Management

Uninstalling the E-Procurement Sample

A script is not provided to remove the files and BizTalk Messaging Configuration objects, such as ports and channels, that are created by running the setup application. The following list contains the BizTalk Messaging Configuration objects, files, folders, and libraries used by this sample. These can be manually deleted when you are finished running this sample.

Organizations

Hub, Supplier

Channels

HubReceivePO, HubSendPO, SupplierReceivePO, HubReceiveInvoice, SupplierSendInvoice, HubSendPayment, SupplierReceivePayment, SupplierSendPaymentAck, HubReceivePaymentAck, HubSendPayAckToFile

Document Definitions

EcommonInvoice, EcommonPayment, EcommonPO, EPaymentAck

Messaging Ports

HubReceivePO, HubSendPO, SupplierReceivePO, HubReceiveInvoice, SupplierSendInvoice, HubSendPayment, SupplierReceivePayment, SupplierSendPaymentAck, HubReceivePaymentAck, HubSendPayAckToFile

Receive Functions (in BizTalk Server Administration):

HubReceiveInvoice, HubReceivePaymentAck, Receive PO, SupplierReceivePayment, SupplierReceivePO

Private Messaging Queues (in Computer Management)

receiveinvoice, receivepayment, receivepaymentack, receivepo, receivepo2, supplierreceivepo, supplierreceivepo2

BizTalk Server Repository Files (WebDAV)

ECommonInvoice.xml, eCommonPayment.xml, ECommonPO.xml, ePaymentAck.xml

Registered Libraries

Correlation.dll, HubTransformation.dll, PaymentTransformation.dll, SuppCorrelation.dll, Transformation.dll

Folders in \Microsoft BizTalk Server\HTTP Receive

Hub
Hub/PaymentAck
Supplier
Supplier/Payment

Note

  • An Internet Information Services virtual directory is associated with each one of these folders.


Optional Monitoring and Deployment Procedures

You must set up and run the e-procurement sample before proceeding. However, the following procedures are optional.

Prerequisites for monitoring and deployment are:

  • To run the deployment procedure you must be running Application Center 2000.

  • The Microsoft Operations Manager (MOM) setup procedure covers MOM configuration for advanced monitoring capabilities. This procedure requires MOM 2000 and the BizTalk Server 2002 Management Pack.

The following topics are covered in this section:

  • Using Application Center for E-Procurement Deployment

  • Creating a SEED Package

  • Creating a MOM Custom Counter for the E-Procurement Sample


Using Application Center for E-Procurement Deployment

Application Center can be used to deploy a BizTalk Server configuration from one environment to another, such as moving a configuration from a test environment to a production environment. Using Application Center to deploy environments greatly reduces both the time it takes to move configurations and the amount of human intervention associated with such a move.

In this scenario, the hub resides on one server (the source) and we deploy the BizTalk Server configuration to another server (the target) within the organization. For the e-procurement sample the hub and supplier configurations were installed on the same computer. Therefore, when we deploy the entire configuration from one environment to another, both the hub and the supplier are included. In a production environment, the hub and supplier would be on different computers, and the supplier would not be included in the deployment.

Note

  • You need to install Application Center before you install BizTalk Server.

Prerequisites for using Application Center for deployment are:

  • To use Application Center for e-procurement deployment, you will need to install Application Center 2000 on two computers. One will serve as the source computer and the other as the target computer. Both computers should also have BizTalk Server 2002 installed and running. In addition, the e-procurement sample must be installed on the source computer and running correctly.

  • After you install Application Center 2000, you must install SP1 for Application Center 2000. SP1 for Application Center 2000 can be found in the Application Center 2000 SP1 directory on the BizTalk Server 2002 installation CD.

  • If clusters are not already created on the computers, you will need to create clusters on both the source and target computers. It is important that the source and target computers be on separate clusters so that the sample can simulate a deployment from one environment to another, such as from a test environment to a production environment.

After the source and target computers are properly configured, use Application Center to create an application on the source computer cluster. For more information, see Using Application Center 2000.

The resource types for this cluster include:

  • File system paths
    • The e-procurement sample site (for example, \eProcurementSample)
  • Web sites and virtual directories
    • Hub virtual directory

    • Supplier virtual directory
  • BizTalk
    • BizTalkPorts

    • BizTalkReceiveFunctions

After the Application Center application is created you can deploy it from the source computer to the target computer. For more information, see Deploy an Application Center application to a target server.

Because the target computer is part of another cluster you must select Deploy content outside the current cluster on the Deployment Target Options page in the Deployment Wizard. The Deployment Wizard also provides a drop-down list of applications that are available for deployment. Choose to deploy the application that you created earlier on the source computer to the target computer.

When deployment is complete you will need to make some minor adjustments on the target computer. For example, if the correlation databases that are used in the e-procurement sample are in use by SQL Server during deployment they cannot be copied to the target computer through Application Center.

To manually copy the correlation databases over to the target computer's SQL Server instance, use the "Attach the databases" functionality described in the Preliminary Setup section for the e-procurement sample. You can also use the Data Transformation Services (DTS) of SQL Server to export the databases to the target computer's SQL Server instance.

In addition, the DLLs used by the e-procurement sample will be copied to the target computer through Application Center, but they will not be registered on the target computer. You can register the necessary DLLs by running the RegisterDLLs.vbs script file located in the \eProcurementSample\Application Center directory. If this is the first time that you have deployed the sample to the target computer, the message queues most likely have not been created on this computer. You can create the necessary message queues by running the CreateQueues.vbs script file located in the \eProcurementSample\Application Center directory.

Note

  • You might need to enable all the BizTalk receive functions used by the e-procurement sample. The receive functions can be enabled in the BizTalk Server Administration application. This action might be needed because the receive functions are created before the message queues are created. BizTalk Server automatically disables receive functions if their corresponding polling locations (directory, message queue, and so on) are not accessible.

Finally, the BizTalk ports on the target computer will need to be changed so that the primary port address points to the target server. When Application Center deploys the BizTalk Server configuration from one computer to another it does not modify the BizTalk ports. They will still point to the source server. The following ports will need to be edited to point to the target server:

  • HubSendPayment

  • HubSendPO

  • SupplierSendInvoice

  • SupplierSendPaymentAck

Note

  • You might need to start and stop the BizTalk service for these changes to take effect. You can start and stop the BizTalk service in the BizTalk Server Administration tool.


Creating a SEED Package

To complete this procedure the e-procurement sample must be installed on this server and running correctly.

This sample shows you how a hub creates a SEED package, how a supplier installs the SEED package, and how the SEED package is tested by the supplier.

In this scenario the hub creates a SEED package that includes specific document specifications to be sent to the trading partner, similar to the supplier organization in this sample. The trading partner installs the SEED package. The e-procurement sample was set up with both the hub and the supplier on one computer. SEED packages are intended to be used in two totally separate environments.

The following topics are covered in this section:

  • Preliminary Setup for the SEED Package

  • Create the SEED Package


Preliminary Setup for the SEED Package

Before you create the SEED package you must create an Internet Information Services (IIS) virtual directory for the SEED package and copy the appropriate .asp files. These will be used for the hub's test site.

Create an IIS virtual directory for the SEED package

  1. Create a new directory named SEEDPackage on the BizTalk Server. This directory will serve as the SEED package test directory.

  2. Create three new directories in the SEEDPackage directory, named SeedTestSite, SeedDropSite, and SeedReceiveSite.

  3. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Internet Services Manager. Expand the current computer listing.

  4. Right-click Default Web Site, point to New, and then click Virtual Directory. The Virtual Directory Creation Wizard appears.

  5. Click Next. A new screen appears that asks for the Virtual Directory Alias. In the Alias field, type SeedTestSite, and then click Next.

  6. A new screen appears that asks for the location to which the virtual directory will point. You can use the Browse button to locate the SeedTestSite directory that you created earlier, or you can type the full path of the SeedTestSite directory in the Directory field. Then click Next.

  7. A new screen appears that gives you the opportunity to change the Access Permissions for the virtual directory. Keep the default settings and click Next. Click Finish on the next screen.

Copy the appropriate files

Copy the following .asp files from the SEED directory located at \Program Files\Microsoft BizTalk Server\SEED:

  • LocalSubmit.asp

  • SlingBack.asp

  • Trigger.asp

Paste the files in the SeedTestSite directory that you created earlier. The SlingBack.asp and Trigger.asp files are used by the hub for remote testing of inbound and outbound documents. LocalSubmit.asp is used by the supplier for remote testing of outbound documents. For more information about the use of these .asp files, see Understanding the ASP Pages in SEED.

Continue to Create the SEED Package.


Create the SEED Package

A SEED package is created by the hub and made available to suppliers. When the hub sets up a partnership with a new supplier, the new supplier downloads the SEED package, installs it, and begins sending documents to the hub's test site. If there are no problems the supplier can integrate this configuration into the production environment and begin e-procurement transactions with the hub. The following procedures show how to set up, install, and test a SEED package.

Note

  • This e-procurement sample was set up with both the hub and the supplier on one computer. SEED packages are intended to be used in two totally separate environments.

To implement the use of a SEED package complete these procedures:

  • Add the Common PO Specification

  • Add the Common Invoice Specification

  • Add the Common Payment Specification

  • Add the Payment Acknowledgement Specification

  • Complete the SEED Package Creation

  • Install the SEED Package

  • Test the SEED Package Specifications


Add the Common PO Specification

The SEED package created by the hub will include CommonPO document specifications.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk SEED Wizard.

  2. The BizTalk SEED Wizard menu appears. The default is Create SEED Package. Click Next.

  3. In the Organization field, type Hub and click Next.

  4. The Package Create Process – Document Specifications menu appears. Click Add.

  5. Next to the Specification field, click Browse. Double-click the eProcurement directory. Double-click the ECommonPO.xml document specification. This automatically fills the Specification field with the location of the schema file.

  6. Next to the Test Instance field, click Browse. Browse to the eProcurementSample directory. In the eProcurementSample directory, double-click the Instances directory. In the Instances directory, double-click CommonPO_Instance.xml. This fills the Test Instance field with the location of the instance file.

  7. Make sure that the Outbound from Initiator option is selected.

  8. In the URL for Remote Test field, the entry should point to the SEED package virtual directory site that was created earlier and the Trigger.asp file. The entry should look similar to this: http://<Server Name>/SeedTestSite/Trigger.asp. The Trigger.asp file is used for remote testing of outbound documents.

  9. Click OK.

Continue to Add the Common Invoice Specification.


Add the Common Invoice Specification

The SEED package created by the hub will also include CommonInvoice document specifications.

  1. On the Package Create Process – Document Specifications menu, click Add. This adds another document to be included in the SEED package for testing.

  2. Next to the Specification field, click Browse. Double-click the eProcurement directory. Double-click the ECommonInvoice.xml document specification.

  3. Next to the Test Instance field, click Browse. Browse to the eProcurementSample directory. In the eProcurementSample directory, double-click the Instances directory. In the Instances directory, double-click CommonInvoice_Instance.xml.

  4. Make sure that the Inbound to Initiator option is selected.

  5. In the URL for Remote Test field, the entry should point to the SEED package virtual directory site that was created earlier and the SlingBack.asp file. The entry should look similar to this: http://<Server Name>/SeedTestSite/SlingBack.asp. The SlingBack.asp file is used for testing of inbound documents.

  6. Because this exercise is to show you how to create a sample SEED package, we will not be pointing to a real production site. So, within the Production URL field, you can copy the value from the URL for Remote Test field. If you had a real production environment, you would enter the production site information in this field.

  7. Click OK.

Continue to Add the Common Payment Specification.


Add the Common Payment Specification

The SEED package created by the hub will also include CommonPayment document specifications.

  1. On the Package Create Process – Document Specifications menu, click Add. This adds another document to be included in the SEED package for testing.

  2. Next to the Specification field, click Browse. Double-click the eProcurement directory. Double-click the ECommonPayment.xml document specification.

  3. Next to the Test Instance field, click Browse. Browse to the eProcurementSample directory. In the eProcurementSample directory, double-click the Instances directory. In the Instances directory, double-click CommonPayment_Instance.xml.

  4. Make sure that the Outbound from Initiator option is selected.

  5. In the URL for Remote Test field, the entry should point to the SEED package virtual directory site that was created earlier and the Trigger.asp file. The entry should look similar to this: http://<Server Name>/SeedTestSite/Trigger.asp. For more information about this file, see Understanding the ASP Pages in SEED.

  6. Click OK.

Continue to Add the Payment Acknowledgement Specification.


Add the Payment Acknowledgement Specification

The SEED package created by the hub will also include Payment Acknowledgement document specifications.

  1. On the Package Create Process – Document Specifications menu, click Add. This adds another document to be included in the SEED package for testing.

  2. Next to the Specification field, click Browse. Double-click the eProcurement directory. Double-click the EPaymentAck.xml document specification.

  3. Next to the Test Instance field, click Browse. Browse to the eProcurementSample directory. In the eProcurementSample directory, double-click the Instances directory. In the Instances directory, double-click PaymentAck_Instance.xml.

  4. Make sure that the Inbound to Initiator option is selected.

  5. In the URL for Remote Test field, the entry should point to the SEED package virtual directory site that was created earlier and the SlingBack.asp file. The entry should look similar to this: http://<Server Name>/SeedTestSite/SlingBack.asp. The SlingBack.asp file is used for testing of inbound documents. For more information about this file, see Understanding the ASP Pages in SEED.

  6. Because this exercise is to show you how to create a sample SEED package, we will not be pointing to a real production site. So, within the Production URL field, you can copy the value from the URL for Remote Test field. If you had a real production environment, you would enter the production site information in this field.

  7. Click OK.

Continue to Complete the SEED Package Creation.


Complete the SEED Package Creation

  1. On the Package Create Process – Document Specifications menu, click Next.

  2. Click Browse and browse to the SEEDPackage directory that you created earlier. Name the SEED package SamplePackage.xml.

  3. Click Finish. A message box appears stating that the SEED package has been successfully created. Click OK.

Continue to Install the SEED Package.


Install the SEED Package

The hub places the SEED package on its Web site for its suppliers to download. A supplier downloads the SEED package and then uses the BizTalk SEED Wizard to complete the configuration. This SEED sample is designed to be created, installed, and deployed on a single computer. In a real-world scenario, the SEED package would be created on one computer and installed on a separate computer.

When the SEED package is installed on the supplier system, it creates the necessary ports, channels, document definitions, and receive functions. The title of each port, channel, document definition, and receive function starts with the name of the SEED package. This naming scheme ensures that unique names are given to the SEED package objects and avoids attempting to create existing objects. This naming scheme also makes the objects distinct from other SEED package objects that might have been installed on the BizTalk Servers.

This procedure assumes that the SEED package is located in a repository that can be accessed by the server.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk SEED Wizard.

  2. The BizTalk SEED Wizard menu appears. Make sure that the Install SEED Package option is selected. Click Next.

  3. Next to the Package File field, click Browse. Browse to the SEEDPackage directory. Double-click the SamplePackage.xml file.

  4. This displays the SEED package information (Package ID, organization, and so on). Click Next. Accept the default settings on the Package Installation Process – Test Information menu and click Next.

  5. The next screen displays the documents that are part of the SEED package. Highlight the EcommonPO.xml specification and click Configure.

  6. In the Production URL field, type http://<Server Name>/SeedTestSite/localsubmit.asp. The localsubmit.asp file is used for remote testing of outbound documents. For more information about this file, see Understanding the ASP Pages in SEED.

  7. Next to the Final Drop Location field, click Browse. Browse to the SeedDropSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedDropSite directory is selected. Click OK.

  8. Highlight the ECommonInvoice.xml specification and click Configure.

  9. Next to the Location field, click Browse. Browse to the SeedReceiveSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedReceiveSite directory is highlighted. Click OK.

  10. In the File types to poll for field, enter CommonInvoice_Instance.xml.

  11. Next to the Text Drop Location field, click Browse. Browse to the SeedDropSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedDropSite directory is highlighted. Click OK.

  12. Click OK.

  13. Highlight the ECommonPayment.xml specification and click Configure.

  14. In the Production URL field, type http://<Server Name>/SeedTestSite/localsubmit.asp. The localsubmit.asp file is used for remote testing of outbound documents. For more information about this file, see Understanding the ASP Pages in SEED.

  15. Next to the Final Drop Location field, click Browse. Browse to the SeedDropSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedDropSite directory is selected. Click OK.

  16. Highlight the EPaymentAck.xml specification and click Configure.

  17. Next to the Location field, click Browse. Browse to the SeedReceiveSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedReceiveSite directory is highlighted. Click OK.

  18. In the File types to poll for field, enter PaymentAck_Instance.xml.

  19. Next to the Test Drop Location field, click Browse. Browse to the SeedDropSite directory in the SEEDPackage directory that you created earlier. Make sure that the SeedDropSite directory is highlighted. Click OK.

  20. Click OK.

Continue to Test the SEED Package Specifications.


Test the SEED Package Specifications

At this point, all the document specifications should have a status of Configure Complete. At this point, the SEED application has not created any new objects (receive functions, ports, channels, and so on). The supplier needs to complete the following steps to test the SEED package.

  1. Highlight the ECommonPO.xml specification. Click Create. After the SEED application creates the necessary objects, the status of the specification should change to Create Passed. This process should be repeated with each of the remaining specifications. After each specification has been created, the Test Locally button will be activated.

  2. Highlight the ECommonPO.xml specification. Click Test Locally. After a specification has passed the local test, its status will change to Local Test Passed and the Test Remotely button will be activated. When the SEED application performs a local test, it creates an instance of the particular specification and sends it directly to the corresponding channel to be verified. In this case, the channel is SamplePackage_ECommonPO. This ensures that the format of the document is correct. If the instance format is correct, the status of the specification within the SEED package is updated. This process should be repeated with each of the remaining specifications. The Test Locally process is different for inbound documents. For more information about SEED's local testing, see Understanding the ASP Pages in SEED.

  3. Highlight the ECommonPO.xml specification. Click Test Remotely. After an inbound specification has passed the remote test, its status will change to Remote Test Passed and the Deploy button will be activated. The Deploy button is not activated for outbound specifications. When the SEED application performs a remote test, it creates an instance of the particular specification and sends it to the remote test URL that was specified when the SEED package was created through HTTP Post to the trigger.asp page, located on the hub. The trigger.asp page sends it back to the supplier, where the document format is verified. If the instance format is correct, the status of the specification within the SEED package is updated. This process should be repeated with each of the remaining specifications. The Test Remotely process is different for inbound documents. For more information about SEED's remote testing, see Understanding the ASP Pages in SEED.

  4. Highlight the ECommonInvoice.xml specification. Click Deploy. After a specification has passed the deployment test, its status will change to Deploy Passed. Repeat the steps with the ePaymentAck.xml specification.

  5. After you have deployed both specifications, click Next. Then click Finish.

Note

  • The ports and channels that are created by SEED in this procedure are not part of the e-procurement sample. In the e-procurement sample the ports and channels were already configured. The SEED procedure outlined here is only for example purposes.

    In a real-world scenario customers would at this point build their schedules around the messaging configuration that SEED provides. In the e-procurement scenario the supplier schedule has already been developed around the messaging configuration needed to do business with the hub.


Creating a MOM Custom Counter for the E-Procurement Sample

The administrators on the hub system might want to monitor transactions with the supplier. Using Microsoft Operations Manager (MOM), the administrators on the hub computers can set up rules to count documents being received or sent to the supplier. This part of the sample details the steps required to make the MOM rules to track CommonInvoice documents received from the supplier.

The following procedures can be completed only if you have installed MOM and the BizTalk Server 2002 Management Pack for advanced monitoring capabilities. To read the results in MOM, the e-procurement sample must be configured and running.

To create and use a custom counter in MOM, complete these procedures:

  • Set Up the Custom Counter

  • Create the MOM Rule

  • Distribute the Rule to the Agent

  • Read the Results in MOM


Set Up the Custom Counter

The following procedure creates the BizTalk Server Windows Management Instrumentation (WMI) customer counter for the CommonInvoice document. The custom counter that is created reads the Tracking database and returns the number of CommonInvoice documents that were processed during the last 300 seconds.

Note

  • This script must be run on the computer that is running BizTalk Server and the MOM Agent.

To set up the custom counter:

  1. Browse to \eProcurementSample\Operations Manager.

  2. Double-click CustomCounter_eProcurement_CommonInvoice.vbs.

  3. A validity check message box appears. Click OK.

Continue to Create the MOM Rule.


Create the MOM Rule

To complete the steps in the following procedures you must have the BizTalk Server 2002 Management Pack installed, and be somewhat familiar with MOM operations.

To create the MOM rule you must start the MOM Administrator Console. All work will be done inside this console.

Fixing the Event Collection Rule group

The Processing Rule group folder named Microsoft BizTalk Server initially does not have a Computer group assignment. Without the assignment, any rule that is placed in the folder will not be propagated to any MOM Agents.

  1. In the MOM Administrator Console, expand Rules and then expand Processing Rule Groups.

  2. Right-click the Microsoft BizTalk Server folder and click Properties.

    This opens a Processing Rule Group Properties dialog box for the folder.

  3. Click the Computer Groups tab.

    This brings up a list of Computer groups that are connected to this folder.

  4. If the list is blank, click Add.

    A Select Item dialog box appears with the list of all MOM Computer groups.

  5. Select Microsoft BizTalk Server 2002 Enterprise Edition.

  6. Click OK to close the Select Item dialog box.

  7. Click OK to close the Properties dialog box.

Creating the MOM Alert Processing Rule

  1. In the MOM Administrator Console, expand Rules, Processing_Rule_Groups, and Microsoft BizTalk Server.

  2. Right-click Performance Processing Rules, point to New, and then click Performance Processing Rule.

    The Performance Processing Rule Type dialog box appears.

  3. Highlight Compare Performance Data (Threshold).

  4. Click Next.

    The Threshold Processing Rule Properties –Data Provider dialog box appears.

  5. Click New to create a new Data Provider.

    The Select Provider Type dialog box appears.

  6. Highlight WMI Numeric Event and click OK.

    The WMI Numeric Provider Properties dialog box appears.

  7. Fill in the following fields:
    • Provider name: Custom Counter for CommonInvoice Documents

    • WMI Namespace: root\MicrosoftBiztalkServer

    • Class of Object to be measured: MSBTS_CustomCounter

    • Object Instance Expression: Name = "Custom Counter for CommonInvoice Documents"

    • Numeric property to sample: MatchCount

    • Text Property to be Instances: Name

    • Sample Every: 10 Seconds

Note

  • Adjusting the sample interval to a small value can impact the performance of both the computer acting as MOM Consolidator and the computers running the MOM Agents.
  8. Click Next.

  9. Leave the Synchronize at check box cleared and click Finish to close the dialog box.

  10. In the Threshold Processing Rule Properties dialog box click Next.

  11. Accept the always process data default on the specify optional schedule page and click Next.

  12. Accept the default (no check boxes selected) on the select the properties you would like to match page, and click Next.

  13. Accept the default on the Specify the threshold value you would like to match page.

    This causes the MOM system to generate an alert when the counter is greater than 0.

  14. Click Next.

  15. On the Specify whether a match to this rule generates an alert page, select Generate Alert; in the Alert Severity list, click Success; and type E-Procurement Sample in the Owner text box . In all other fields accept the default.

  16. Click Next.

  17. On the Define the handling of duplicate alerts page, clear the suppress duplicate alerts check box if you want to get an alert every time the condition is met. Otherwise you will get only one alert.

  18. Click Next.

  19. On the Define any response action page, click Next.

  20. On the Company Knowledge Base page, click Next.

  21. On the Specify the Comments for the Knowledge Base Entry page, accept the defaults and click Next. Note that this page will only be available if you have a MOM Knowledge Authorizing License installed.

  22. On the Specify the advanced setting properties page, accept the defaults and click Next. Note that this page will only be available if you have a MOM Knowledge Authorizing License installed.

  23. On the Enter a name for the processing rule page, type eProcurement-CustomCounter for CommonInvoice and click Finish.

Continue to Distribute the Rules to the Agent.


Distribute the Rules to the Agent

At this point the rules are updated but not published to the MOM Agents for processing. To distribute the rules to the Agent, right-click Rules in the MOM console and click Commit Configuration Changes. It might take a few minutes for the MOM system to transfer the rules to the Agents.

Continue to Read the Results in MOM.


Read the Results in MOM

Every time you run the e-procurement sample script a CommonInvoice document is generated in the hub schedule. For example, if you run DocumentGenerator.vbs three times in rapid succession the MOM Agents will sample the CustomCounter value and trigger an alert.

To view the alert, expand the Monitor folder in the MOM console and select all open alerts. There should be at least one alert with a green check mark and the Severity of Success. The Owner column should read e-procurement sample.


BizTalk Server 2002 Administration

Microsoft® BizTalk™ Server 2002 administration is divided into the following parts:

Installing BizTalk Server 2002

This section provides information about installing BizTalk Server 2002. The information includes guidelines for hardware and software requirements, and instructions for complete, tools, and custom installations. For more information, see Installing BizTalk Server 2002.

Understanding Security

This section covers how businesses can securely exchange data with trading partners when they use BizTalk Server 2002. BizTalk Server takes advantage of the security features included in Microsoft Windows® 2000. For more information, see Understanding Security.

Enhancing Performance and Scalability

The section provides information about enhancing the performance of BizTalk Server and creating scalable solutions. Issues and guidelines covered in this section include identifying potential bottlenecks, addressing latency, and managing databases. For more information about creating a scalable, high-performance solution, see Enhancing Performance and Scalability.

Administering Servers and Applications

This section covers how to administer servers and XLANG-related applications. Topics covered in this section include centrally configuring and managing servers in multiple groups, configuring and managing receive functions, managing the Shared queue, and managing the COM+ applications that host XLANG schedules. For more information, see Administering Servers and Applications.

Tracking Documents

This section provides information about how to track interchanges and documents processed by BizTalk Server 2002. Topics covered in this section include how to create queries and advanced queries, how to save interchange, document, and custom-search data, and understanding interchange record, document record, and receipt results. For more information, see Tracking Documents.

Monitoring Documents

This section provides information about the BizTalk Server 2002 Enterprise Edition Management Pack for Microsoft Operations Manager (MOM). This information includes the performance counters, Microsoft Windows NT® event rules, user-configured rules, and views available in this Management Pack to enhance the MOM capabilities by monitoring events specific to BizTalk Server. For more information, see Monitoring Documents.

Note

  • The file path to open various Windows 2000 services and tools, such as Component Services or Administrative Tools, is different depending on whether you are using a computer that is operating on Windows 2000 Server or Windows 2000 Professional. For more information, see Open Component Services.

    In Microsoft BizTalk Server 2002 Help, the paths to these services and tools have been documented based on a Windows 2000 Server installation. If you are using Windows 2000 Professional, refer to Windows 2000 Professional Help for more information about how to open the service or tool that you are interested in using.

Related Topic

BizTalk Server Administration Model


Installing BizTalk Server 2002

Welcome to the Microsoft® BizTalk™ Server 2002 installation guide. It provides guidelines for hardware and software requirements, and complete instructions for the following installation options:

  • Complete Installation. Enables you to perform a complete installation of BizTalk Server 2002 that includes all BizTalk services, tools, and samples.

  • Tools Installation. Enables you to perform a complete installation of the BizTalk Server 2002 tools, including BizTalk Orchestration Designer, BizTalk Editor, BizTalk Mapper, the BizTalk Server Administration Microsoft Management Console (MMC) snap-in, and BizTalk Server 2002 Help. The BizTalk Server 2002 parser, serializer, correlation, and run-time binaries are not installed.

  • Custom Installation. Enables you to perform a custom installation that includes any combination of BizTalk Server 2002 tools and services.

  • Upgrade Installation. Enables you to upgrade from BizTalk Server 2000 tools and services to BizTalk Server 2002 tools and services.

  • Silent Installation. Enables you to install BizTalk Server 2002 silently by specifying property values from the command line.

  • Removing BizTalk Server 2002. Enables you to remove your installation of BizTalk Server 2002.

The following topics are covered in this guide:

  • Installation Checklist

  • Hardware and Software Requirements

  • Installation Instructions


Installation Checklist

This checklist describes the steps required to set up a complete installation of Microsoft® BizTalk™ Server 2002 and all its components. Each step refers you to instructions that are needed to complete the step. For best results, print this checklist for referencing during setup.

Step | Reference
Check hardware requirements. | Minimum Hardware Requirements
Check software requirements. | Software Requirements
View Readme file for latest developments. | The Readme file is located on the root directory of the BizTalk Server installation CD.
Install Microsoft Windows® 2000 operating system. | Windows 2000 Prerequisites and Installation Requirements
Install Microsoft Message Queuing. | Install Message Queuing
Install Internet Information Services. | Install Internet Information Services (IIS)
Configure Internet Information Services. | Configure IIS settings for BizTalk Server 2002
Install Windows 2000 Service Pack. | Install Windows 2000 Service Pack 2
Add your user account to the Windows 2000 Administrators group and create a BizTalk Server service account. | Set up a service account
Install Microsoft SQL Server™. | SQL Server Prerequisites and Installation Requirements
Install SQL Server Service Pack. | Install the Service Pack for SQL Server
Verify that SQL Server is running. | Verify that SQL Server is running
Add a SQL Server Login account (for remote SQL Server installations). | SQL Server and BizTalk Server 2002 Database Interactions
Install Microsoft Visio® 2002. | Installing Visio 2002
Install Microsoft Application Center 2000 SP1. | Installing Application Center 2000
Install BizTalk Server 2002. | Installation Instructions
Establish remote database permissions if SQL Server is installed on a remote computer. | SQL Server and BizTalk Server 2002 Database Interactions
Configure COM+ applications to run as something other than Interactive User. | Change the application identity for a COM+ application
Start the World Wide Web Publishing Service. | Start the World Wide Web Publishing Service
Configure Internet Explorer for BizTalk Document Tracking. | Configuring BizTalk Document Tracking


Hardware and Software Requirements

This section includes information about minimum hardware requirements and configuration options to install Microsoft BizTalk Server 2002. It also includes installation instructions for the prerequisite software for BizTalk Server 2002.

The following topics are covered in this section:

  • Minimum Hardware Requirements

  • Recommended Configuration to Optimize Performance for Document Messaging

  • Software Requirements

  • Windows 2000 Prerequisites and Installation Requirements

  • SQL Server Prerequisites and Installation Requirements

  • Installing Visio 2002

  • Installing Application Center 2000


Minimum Hardware Requirements

The minimum hardware requirements for a complete installation of Microsoft BizTalk Server 2002 include:

  • 400 megahertz (MHz) or higher Intel® Pentium®-compatible CPU

  • 256 megabytes (MB) of RAM

  • 6-gigabyte (GB) hard disk

  • CD-ROM drive

  • Network adapter card

  • VGA or Super VGA monitor

  • Microsoft Mouse or compatible pointing device

Note

  • During BizTalk Server 2002 installation, the installation program determines the hard disk space that is available on your computer. A complete installation requires approximately 52 MB of hard disk space, not including the requirements of the BizTalk Messaging Management database, the Tracking database, the Shared Queue database, and the Orchestration Persistence database. A tools installation requires approximately 30 MB of hard disk space. A custom installation requires approximately 2 to 52 MB of hard disk space, not including database requirements, depending on the services and tools that you install.


Recommended Configuration to Optimize Performance for Document Messaging

The following are guidelines to help you achieve optimal performance with Microsoft BizTalk Server 2002:

  • Build a three-computer configuration. In the three-computer configuration, install BizTalk Server 2002 on one computer, install the Tracking database on a second computer, and install the BizTalk Messaging Management and Shared Queue databases on a third computer.

  • Instead of using a single server to perform all the processing and receiving functions, performance can be optimized by configuring two BizTalk Server 2002 servers, one dedicated to processing and the other dedicated to receiving.

  • Install the Tracking database on a computer with multiple physical hard disks. The optimal configuration includes four SCSI II hard disks and a SCSI II controller. The first hard disk is dedicated to document-tracking storage. The second hard disk is dedicated to the Microsoft Windows® 2000 system page file. The third hard disk is dedicated to the Tracking transaction log. The fourth hard disk is dedicated to the Distributed Transaction Coordinator (DTC) log.

  • Create multiple instances of receive functions to monitor multiple receive locations for documents that are to be processed. To balance the load of documents across several computers, locate the receive functions on separate computers. Each monitoring location must be unique and must have a separate receive function. To avoid overloading any individual receive function, the business application that sends documents must evenly distribute the documents to all the monitoring locations.

Important

  • Do not install the BizTalk Messaging Manager tool, Internet Information Services (IIS), and the Biztalk Server configuration database on three separate computers. This type of configuration causes authentication problems. For more information, see Authentication problems when IIS, BizTalk Messaging Manager tool, and SQL Server are on three different computers.

  • For more information about performance enhancements to BizTalk Server, see Enhancing Performance and Scalability.


Software Requirements

The following table lists the software that must be installed to run Microsoft BizTalk Server 2002.

Complete installation | Tools installation | Custom installation
Microsoft Windows 2000 with Service Pack 2 (SP2)* and the NTFS file system | Microsoft Windows 2000 with Service Pack 2 (SP2)* and the NTFS file system, or Windows XP Professional or later | Microsoft Windows 2000 with Service Pack 2 (SP2)* and the NTFS file system
Microsoft Internet Explorer 5.5 or later | Microsoft Internet Explorer 5.5 or later | Microsoft Internet Explorer 5.5 or later
Microsoft Visio® 2002, (required to use BizTalk Orchestration Designer) | Microsoft Visio 2002, (required to use BizTalk Orchestration Designer) | Microsoft Visio 2002, (required to use BizTalk Orchestration Designer)
Microsoft SQL Server 7.0 with Service Pack 3 (SP3) or SQL Server 2000 SP1 | Microsoft SQL Server 7.0 with Service Pack 3 (SP3) or SQL Server 2000 SP1
Note
  • BizTalk Messaging Manager will not run unless the World Wide Web Publishing Service is running.
 Note
  • BizTalk Messaging Manager will not run unless the World Wide Web Publishing Service is running.
 Note
  • BizTalk Messaging Manager will not run unless the World Wide Web Publishing Service is running.

*Windows 2000 system console must be used to install BizTalk Server 2002. Using Terminal Services to install BizTalk Server is not supported.

Notes

  • Microsoft SQL Server is required for a custom installation only if you install the core BizTalk Services. It is not required for a tools installation.

  • Microsoft Application Center 2000 with SP1 is required only if you want to take advantage of BizTalk Server 2002 deployment capabilities. For more information, see Installing Application Center 2000.

  • Microsoft Operations Manager (MOM) 2000 is required only if you plan to install the BizTalk Server 2002 Management Pack for advanced monitoring capabilities. For more information about the BizTalk Server 2002 Management Pack, see Import the BizTalk Server 2002 Management Pack.


Windows 2000 Prerequisites and Installation Requirements

Microsoft Windows 2000 with Service Pack 2 (SP2) is required for all Microsoft BizTalk Server 2002 installations. Because BizTalk Server 2002 has been thoroughly tested on Windows 2000 SP2, this installation guide includes information regarding the necessary configuration of Windows 2000 Server, Windows 2000 Advanced Server, and Windows 2000 Professional in combination with BizTalk Server. You must also install Message Queuing and Internet Information Services (IIS) with your Windows 2000 installation. For more information, see Install Message Queuing and Install Internet Information Services (IIS). If your installation of Windows 2000 does not include Service Pack 2, you must install it. For more information, see Install Windows 2000 Service Pack 2.

After installing Windows 2000, you must add a Windows 2000 user account to the Administrators group before you install any additional software.

The following topics are covered in this section:

  • Install Windows 2000 Server, Advanced Server, or Professional

  • Install Message Queuing

  • Install Internet Information Services (IIS)

  • Configure IIS settings for BizTalk Server 2002

  • Install Windows 2000 Service Pack 2

  • Set up a service account


Install Windows 2000 Server, Advanced Server, or Professional

If Windows 2000 Server, Advanced Server, or Professional is already installed on your computer, check to make sure that you meet the requirements listed in this topic.

If Windows 2000 is not installed on your computer, insert the Windows 2000 compact disc into your CD-ROM drive and follow the on-screen instructions. The setup wizard guides you through the steps necessary to install Windows 2000.

Observe the following requirements:

  • Use only alphanumeric characters in the computer name because Microsoft SQL Server supports a limited character set in server computer names.

  • Format the partition with the NTFS file system.

  • On the Windows 2000 Components page, in the Components list, click Message Queuing Services. If you are installing Windows 2000 Professional, click Internet Information Services (IIS) and click Next. On the Message Queuing Type page, click Next.

  • On the Network Settings page, click Typical settings.

Notes

  • If you did not select Message Queuing Services on the Windows 2000 Components page during setup, you must install it before you install the Windows 2000 Service Pack. For more information, see Install Message Queuing.

  • If you did not select Internet Information Services (IIS) on the Windows 2000 Components page during setup of Windows 2000 Professional, you must install it before you install the Windows 2000 Service Pack. For more information, see Install Internet Information Services (IIS).

  • If your installation did not include Service Pack 2, you must install it. For more information, see Install Windows 2000 Service Pack 2.

  • The Windows 2000 partition must be converted to the most recent version of NTFS. Setup automatically performs this update if the existing file system is the old version of NTFS. If the existing partition is FAT or FAT32, you are given the option to convert to NTFS. When prompted, choose NTFS.

  • After installing Windows 2000 Server, Advanced Server, or Professional, you must add a Windows 2000 user account to the Administrators group before you install any additional software.


Install Message Queuing

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Add/Remove Programs.

    The Add/Remove Programs dialog box appears.

  3. Click Add/Remove Windows Components.

    The Windows Components Wizard opens.

  4. In the Components list, select the Message Queuing Services check box and click Next.

  5. On the Message Queuing Type page, click Next.

  6. Click Finish to close the wizard.

Note

  • Accept the default settings when installing the Message Queuing Services component.


Install Internet Information Services (IIS)

Notes

  • If you did not select Internet Information Services (IIS) on the Windows 2000 Components page during setup of Windows 2000 Professional, you must install it before you install the Windows 2000 Service Pack. Windows 2000 Professional does not install IIS by default unless you upgrade to Windows 2000 from a previous version of Windows and Personal Web Server (PWS).

  • IIS is installed by default with Microsoft Windows 2000 Server.
  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Add/Remove Programs.

    The Add/Remove Programs dialog box appears.

  3. Click Add/Remove Windows Components.

    The Windows Components Wizard opens.

  4. In the Components list, select the Internet Information Services (IIS) check box and click Next.

  5. Click Finish to close the wizard.


Configure IIS settings for BizTalk Server 2002

To avoid problems accessing and saving specifications to the BizTalk Server 2002 repository, you must turn off the Enable authoring option in Internet Information Services (IIS).

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Internet Services Manager.

  2. Click the expand indicator (+) for the local IIS server.

  3. Right-click Default Web Site and click Properties.

    The Default Web Site Properties dialog box appears.

  4. Click the Server Extensions tab and clear the Enable authoring check box.


Install Windows 2000 Service Pack 2

  • Insert the Windows 2000 SP2 compact disc into the CD-ROM drive and follow the on-screen instructions.

    You can also go to the downloads area of the Microsoft Windows 2000 Web site (www.microsoft.com/windows2000/) to download Windows 2000 SP2 or to order the compact disc.


Set up a service account

To install the remaining software, you need to make sure that the account performing the installation is in the local Windows 2000 Administrators group of the server(s) onto which the software is being installed. This includes any remote SQL Server computers. In addition, you may choose to create a service account for the BizTalk Messaging Service to use to log on. If you choose not to create a service account, you have the option during setup to configure the BizTalk Messaging Service to run as Local System.

Note

  • If you plan to install BizTalk Server and SQL Server on two different computers, the BizTalk Server service account must have permissions to access the computer running SQL Server. For more information, see SQL Server and BizTalk Server 2002 Database Interactions.
  1. Log on as the Administrator.

  2. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

    The Computer Management dialog box appears.

  3. In the console tree, expand System Tools and click Local Users and Groups.

  4. Click Users, right-click anywhere in the details pane, and then click New User.

    The New User dialog box appears.

  5. In the User name box, type a name for the service account; in the Password box, type a password; and then type the same password in the Confirm password box.

  6. Clear the User must change password at next logon check box, click Create, and then click Close.

  7. Close the Computer Management window.

  8. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Local Security Policy.

    The Local Security Settings dialog box appears.

  9. In the console tree, expand Local Policies and click User Rights Assignment.

  10. In the details pane, double-click Act as part of the operating system, click Add, click the service account name you just created from the list, click Add, and then click OK twice.

  11. Repeat step 10 for the Log on as a service policy.

    Important

    • These permissions will not take effect until you restart the computer.

If BizTalk Server 2002 is already installed using an account that is part of the Administrators group, complete the following steps after you have created a service account.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Services.

  2. In the details pane, double-click BizTalk Messaging Service.

    The BizTalk Messaging Service Properties (Local Computer) dialog box appears.

  3. Click the Log On tab and click This account.

  4. Click Browse, locate the service account name you created, and double-click it.

  5. In the Password box, type the same password you previously associated with the service account name; in the Confirm Password box, type the password again and then click OK.

  6. A message box appears; click OK.

  7. Restart the computer.


SQL Server Prerequisites and Installation Requirements

Prior to installing Microsoft BizTalk Server 2002, you must install Microsoft SQL Server 7.0 with Service Pack 3 (SP3) or Microsoft SQL Server 2000 with Service Pack 1 (SP1). When you install BizTalk Server 2002, the installation procedure creates four BizTalk Server 2002 databases (the BizTalk Messaging Management database, the Shared Queue database, the Tracking database, and the Orchestration Persistence database) within SQL Server.

Important

  • If you plan to install BizTalk Server 2002 on a computer running Microsoft Windows 2000 Professional, you must install the Standard or Enterprise Edition of SQL Server on a separate computer. Then, when you install the databases for BizTalk Server 2002, you will need to specify the name of the computer where you installed SQL Server. The Standard and Enterprise Editions of SQL Server cannot be installed on Windows 2000 Professional.

  • If you plan to install BizTalk Server and SQL Server on two different computers, your logon account and the BizTalk Server service account must have System Administrator permissions on both computers. For more information, see SQL Server and BizTalk Server 2002 Database Interactions.

By default, when you install SQL Server 2000, the authentication mode is set to Windows 2000 only. BizTalk Server 2002 uses Windows Authentication to access the BizTalk Messaging Management, Shared Queue, and Tracking databases and the BizTalk Document Tracking Web application. Verify that the SQL Server authentication mode is set to Windows before installing BizTalk Server 2002. For more information, see Set SQL authentication mode for SQL Server 2000.

A cluster is a collection of servers that act as a single server. If you install SQL Server on a cluster and you plan to install BizTalk Server 2002 on another computer, you must install SQL Server client tools on the computer where BizTalk Server 2002 is installed. For more information, see Install SQL Server client tools. When the tools installation is complete, you must use the Client Network Utility to change the default network library from named pipes to TCP/IP. For more information, see Change the default network library to TCP/IP.

International Issue

  • When you install SQL Server, it is important to use the correct collation settings. Collation refers to a set of rules that determines how data is sorted and compared. Character data is sorted using rules that define the correct character sequence, with options for specifying case sensitivity, accent marks, kana character types, and character width. For instance, to store Japanese characters, select case-sensitive sort order to distinguish Japanese-Hiragana from Japanese-Katakana when setting up SQL Server. For more information about collation settings, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online. The topics "Using SQL Collations" and "Windows Collation Sorting Styles" provide additional information.

If SQL Server is set to use Binary Sort Order, then case sensitivity is observed.

The following topics are covered in this section:

  • Install SQL Server 7.0 or 2000

  • Check for SQL Server Service Pack

  • Install the Service Pack for SQL Server

  • Install SQL Server client tools

  • Change the default network library to TCP/IP

  • Set SQL authentication mode for SQL Server 2000

  • Verify that SQL Server is running

  • SQL Server and BizTalk Server 2002 Database Interactions


Install SQL Server 7.0 or 2000

To install SQL Server, insert the Microsoft SQL Server compact disc into the CD-ROM drive and follow the on-screen instructions. The setup wizard walks you through the steps necessary to install SQL Server.

Observe the following requirements:

  • On the Setup Type page, click Typical.

  • On the Services Accounts page, use a domain user account (if connected to a network).

  • When installing SQL Server 2000, specify Windows Authentication.

Important

  • After you install SQL Server, you must install the latest SQL Server Service Pack. You can check to see whether you have the latest Service Pack installed by using Query Analyzer. For more information, see Check for SQL Server Service Pack. For more information about installing SQL Server Service Packs, see Install the Service Pack for SQL Server.


Check for SQL Server Service Pack

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Query Analyzer.

    The Connect to SQL Server dialog box appears.

  2. Click OK.

    If your server name does not appear in the SQL Server list, type it in, and then click OK.

  3. In the Query box, type SELECT @@VERSION.

  4. On the Query menu, click Execute.

    The first line of the query return indicates the version of SQL Server that is running.


Install the Service Pack for SQL Server

  1. Insert the SQL Server Service Pack compact disc into the CD-ROM drive.

  2. Run the SQL Server Service Pack Setup program and follow the on-screen instructions.

    You can also go to the downloads area of the Microsoft SQL Server Web site (www.microsoft.com/sql/) to download the Service Packs for SQL Server, or to order the compact disc.


Install SQL Server client tools

Important

  • If you are in a cluster environment and SQL Server and BizTalk Server are installed on different computers, the SQL Server client tools must be installed on the computer where BizTalk Server 2002 is installed.

To install SQL Server client tools, insert the Microsoft SQL Server compact disc into the CD-ROM drive and follow the on-screen instructions. The setup wizard walks you through the steps necessary to install SQL Server.

Observe the following requirements:

  • On the Installation Selection page, click Create a new instance of SQL Server, or install Client Tools.

  • On the Installation Definition page, click Client Tools Only.


Change the default network library to TCP/IP

When you install SQL Server client utilities, SQL Server Setup installs Named Pipes as the default client network library. BizTalk Server uses TCP/IP for communication with SQL Server, so you will need to change the default network library to TCP/IP.

To change the default network library in SQL Server 7.0:

  1. On the Start menu, point to Programs, point to Microsoft SQL Server 7.0, and then click Client Network Utility.

    The SQL Server Client Network Utility dialog box appears.

  2. On the General tab, select TCP/IP from the Default network library list.

  3. Click OK.

To change the default network library in SQL Server 2000:

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Client Network Utility.

  2. On the General tab, verify that TCP/IP is in the Enabled protocols by order list, and then click the up arrow button to move TCP/IP so that it is the first protocol in the list.


Set SQL authentication mode for SQL Server 2000

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers and expand SQL Server Group.

  3. Right-click the name of your server and click Properties.

    The SQL Server Properties dialog box appears.

  4. Click the Security tab, click Windows Only, and then click OK.


Verify that SQL Server is running

Before installing BizTalk Server 2002, verify that SQL Server is running on your server. This is necessary because BizTalk Server 2002 must create four SQL databases during installation.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server (if you installed SQL Server 2000) or Microsoft SQL Server 7.0 (if you installed SQL Server 7.0), and then click Service Manager.

    The SQL Server Service Manager dialog box appears.

  2. In the Server list, verify that the name of the server is the name of your computer.

    If it is not, click the drop-down arrow to view a list of available servers and scroll to locate your server.

  3. In the Services list, click MSSQLServer (for SQL Server 7.0) or SQL Server (for SQL Server 2000).

  4. Verify that the MSSQLServer or SQL Server service is running.

    The service is running if the Start/Continue button in the dialog box is unavailable. Also, at the bottom of the dialog box is a message that states that the service is running. For example, \\<server name>—MSSQLServer—Running.

  5. If the service is not running, the Start/Continue button is available; click it to start the service.


SQL Server and BizTalk Server 2002 Database Interactions

To avoid unnecessary disk space allocation, use the Truncate log on checkpoint and Auto shrink features of Microsoft SQL Server. Otherwise, the SQL Server logs can consume large amounts of disk space. However, you need to install BizTalk Server 2002 before you can complete this procedure. For more information, see Avoid unnecessary disk space allocation. For more information about installing BizTalk Server 2002, see Installation Instructions.

BizTalk Server 2002 uses Windows Authentication to access the BizTalk Messaging Management, Shared Queue, and Tracking databases and the BizTalk Document Tracking Web application. If you plan to install BizTalk Server and SQL Server on two different computers, the account you are using must have Administrative permissions on the computer running SQL Server and the computer running BizTalk Server.

International Issue

  • BizTalk Server cannot access databases created by a different language version of BizTalk Server.

The following procedures are necessary to establish permissions for remote SQL Server installations and to establish permissions on the remote server to the appropriate BizTalk Server databases.

Remote SQL Server login account

Note

  • By default, if SQL Server and BizTalk Server 2002 are both installed on the local computer, and the BizTalk Server Messaging service account has been added to the Administrators group on the local computer, then it already has System Administrator permissions in SQL Server and the following procedure is not necessary. If, however, you are installing BizTalk Server and SQL Server on separate computers, you must perform the following procedure in order for BizTalk Server 2002 to be able to access SQL Server.
  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server to which you want to add a SQL Server login account, and then expand Security.

  3. Right-click Logins and click New Login.

    The SQL Server Login Properties - New Login dialog box appears.

  4. On the General tab, in the Name box, specify a domain and Windows account name.

    For example: <DOMAIN>\<service account>, specifying the name of the account under which BizTalk Messaging Services will run.

  5. On the Server Roles tab, in the Server Roles list, select the System Administrators check box.

Note

  • Administrative privileges are not required for the service account for the BizTalk Messaging Service to run properly.
  6. Click OK to exit the SQL Server Login Properties page.

Establish remote database permissions

After BizTalk Server 2002 is installed, you will need to specify the databases that can be accessed by the SQL Server login account. Complete the following steps to give the SQL Server login account permissions to the BizTalk Messaging Management, Shared Queue, and Tracking databases.

Note

  • This procedure cannot be completed until BizTalk Server has been installed.
  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server that contains the BizTalk Server databases, expand Security, and then click Logins.

  3. In the details pane, double-click the SQL Server login account that you created for the BizTalk Server Messaging service account.

    The SQL Server Login Properties page appears.

  4. On the Database Access tab, select the InterchangeBTM check box.

    The account name you specified appears in the User box. The Permit in Database Role box automatically appears at the bottom of this page.

  5. In the Permit in Database Role box, select the db_owner and dta_ui_role check boxes.

  6. Repeat steps 4 and 5 for the InterchangeDTA and InterchangeSQ databases, selecting only db_owner in the Permit in Database Role box.

    Note

    • During setup, the BizTalk Messaging Management database object name defaults to InterchangeBTM; the Tracking database object name defaults to InterchangeDTA; and the Shared Queue database object name defaults to InterchangeSQ. You might have renamed these default database object names during setup.


Installing Visio 2002

Because BizTalk Orchestration Designer is a Microsoft Visio 2002-based user interface, you must have Visio 2002 installed on your computer prior to using BizTalk Orchestration Designer. BizTalk Orchestration Designer has been fully tested with Visio 2002.

Install Visio 2002 Standard Edition

  1. Insert the Visio 2002 compact disc into the CD-ROM drive.

  2. Run the Visio 2002 Setup program and follow the on-screen instructions.

For more information, see the Microsoft Visio 2002 documentation.

International Issue

  • In some languages, certain characters might not display properly in BizTalk Orchestration Designer. To correct this, specify that Microsoft Visio 2002 must always use the system default font:
    1. On the Start menu, point to Programs and click Microsoft Visio.

    2. On the Tools menu, click Options.

    3. Click the Regional tab and, in the Document base font area, select Always use the system default font.

    4. Close Visio and open BizTalk Orchestration Designer.


Installing Application Center 2000

Microsoft Application Center 2000 with Service Pack 1 (SP1) is required only if you want to take advantage of BizTalk Server 2002 deployment capabilities.

Important

  • Application Center must be installed before you install BizTalk Server and must be installed on the same computer as BizTalk Server.

  • Application Center 2000 cannot be installed on a computer running Microsoft Windows 2000 Datacenter Server.

Install Application Center 2000

  1. Insert the Application Center 2000 compact disc into the CD-ROM drive.

  2. Run the Application Center 2000 Setup program and follow the on-screen instructions.

Important

  • After you install Application Center 2000, you must install SP1 for Application Center 2000. For more information about installing the patch, see the Readme file in the Application Center 2000 SP1 directory.

  • If Application Center is not installed before BizTalk Server is installed, the driver and enumerator are installed to the AppCenter directory in the BizTalk Server installation directory and are not registered.

    To register the driver and enumerator:

    1. Install Application Center 2000 and SP1.

    2. Copy rdrvbts.dll and AcBtsEnm.dll from \Program Files\Microsoft BizTalk Server\AppCenter to the Application Center installation directory.

    3. Copy the GIF files from \Program Files\Microsoft BizTalk Server\AppCenter\Images to the Admin\Images folder in the Application Center installation directory.

    4. Register the driver and enumerator by executing "regsvr32.exe rdrvbts.dll" and "regsvr32.exe AcBtsEnm.dll" from the command line. You might need to specify a full path name to the dynamic-link libraries (DLLs).


Installation Instructions

You can install Microsoft BizTalk Server 2002 by using the Installation Wizard (Microsoft BizTalk Server.msi) or by using Microsoft Windows Installer (Msiexec.exe). The Installation Wizard is a step-by-step process in which you select options that correspond to specific property values. The Microsoft Windows Installer enables you to specify property values from the command line. You can use this method to install BizTalk Server 2002 silently (without constant interaction or prompts). A silent installation of BizTalk Server 2002 is ideal for test scenarios or as part of a large-scale enterprise deployment.

Regardless of which installation you perform, it is recommended that you maintain a record of the following information for later use:

  • BizTalk Server group names
    Default: BizTalk Server Group

  • Microsoft SQL Server names
    Default: the computer name where SQL Server is installed

  • User names and passwords for the BizTalk Server service account

  • BizTalk Messaging Management database name
    Default: InterchangeBTM

  • Tracking database name
    Default: InterchangeDTA

  • Shared Queue database name
    Default: InterchangeSQ

  • Orchestration Persistence database name
    Default: XLANG

  • WebDAV repository URL
    Default: \\localhost\BizTalkTracking

Important

  • Before you run the installation program for BizTalk Server 2002, verify that you are logged on to the computer using an account that has Administrative permissions on the local computer and on all SQL Server computers you intend to configure. For more information about creating a SQL Server login account with Administrative permissions on a remote computer, see SQL Server and BizTalk Server 2002 Database Interactions.

  • BizTalk Server 2002 requires Microsoft XML Parser (MSXML) version 3.0 with Service Pack 1 (SP1). This release of BizTalk Server 2002 automatically installs MSXML 3.0 SP1. Using BizTalk Server 2002 with a different version of MSXML might produce unpredictable results. If a side-by-side installation of MSXML 3.0 and 4.0 (or later) is necessary, you must uninstall MSXML 4.0 before installing BizTalk Server 2002, and then reinstall MSXML 4.0 after BizTalk Server has been installed.

  • The Windows 2000 system console must be used to install BizTalk Server 2002. Using Terminal Services to install BizTalk Server is not supported.

Notes

  • For detailed information about BizTalk Server security issues, see Security Guidelines.

  • For more information about deploying BizTalk Server 2002 in a cluster environment, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk) and browse to the Deployment page, which is located in the Technical Resources section.

The following topics are covered in this section:

  • Complete Installation

  • Tools Installation

  • Custom Installation

  • Upgrade Installation

  • Silent Installation

  • Removing BizTalk Server 2002


Complete Installation

You can use the following section to perform a complete installation of Microsoft BizTalk Server 2002 that includes all BizTalk services, tools, and samples.

Important

  • Before installing BizTalk Server 2002 you must be in compliance with the minimum hardware and software requirements. To ensure that you have implemented the necessary prerequisites, see the Installation Checklist.

  • To successfully install BizTalk Server, IIS must be enabled. The service will be started during the BizTalk Server installation process.

  • BizTalk Server 2002 uses Windows Authentication to access the BizTalk Messaging Management, Shared Queue, and Tracking databases, and the BizTalk Document Tracking Web application. Verify that the Microsoft SQL Server authentication mode is set to Windows before installing BizTalk Server 2002. For more information, see Set SQL authentication mode for SQL Server 2000. If SQL Server is installed on a remote computer, verify that the account you are using is a member of the SQL Server Administrators group. For more information, see SQL Server and BizTalk Server 2002 Database Interactions.

  • BizTalk Server 2002 requires Microsoft XML Parser (MSXML) version 3.0 with Service Pack 1 (SP1). This release of BizTalk Server 2002 automatically installs MSXML 3.0 SP1. Using BizTalk Server 2002 with other versions of MSXML might produce unpredictable results. If a side-by-side installation of MSXML 3.0 and 4.0 (or later) is necessary, you must uninstall MSXML 4.0 before installing BizTalk Server 2002, and then reinstall MSXML 4.0 after BizTalk Server has been installed.

Perform a complete installation of BizTalk Server 2002

  1. Insert the Microsoft BizTalk Server 2002 compact disc into the CD-ROM drive to start the Installation Wizard. The Installation Wizard guides you through the steps necessary to install BizTalk Server 2002. You must observe the requirements listed in the following steps.

  2. On the Customer Information page, type your name in the User name box, type the name of your company in the Organization box, and then click Next.

  3. On the Destination Folder page, click Next to install BizTalk Server 2002 to the default location: C:\Program Files\Microsoft BizTalk Server, or click Change to select another location.

  4. On the Setup Type page, click Complete and click Next.

  5. On the Configure BizTalk Server Administrative Access page, accept the default group name, BizTalk Server Administrators, or type the group name that you want to use in the Group name box.

    Important

    • Do not rename this group without also modifying the value of "AdminGroupName" in the Windows registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\
      BizTalk Server\1.0\NTGroups      . BizTalk Server 2002 uses this registry key to find the group.

    Note

    • To create a group name, adhere to the following group naming restrictions:

      The group name must be different from any other group or user name on this computer.

      The group name cannot contain the following characters: `~ ! @ # $ % ^ & * ( ) + = [ ] { } | ; \ " ' < > , . ?

      The group name cannot consist solely of periods (.) or spaces.

  6. In the Group description box, type a new description for the group name or accept the default and click Next.

  7. On the Microsoft BizTalk Server Service Log On Properties page, accept the default setting This account to specify a service account. This is the account that the BizTalk Messaging Service will run under. This account must have access to SQL Server for BizTalk Messaging to run properly. Type a valid password in the Password box.

    If you do not want BizTalk Services to automatically start when setup completes, clear the Start service after setup completes check box. The BizTalk Server messaging services will not automatically start.

    Notes

    • BizTalk Server setup will grant Log on as a service and Act as part of the operating system rights to the account specified on the Microsoft BizTalk Server Service Log On Properties page.

    • If you select This account, and intend to use public or private key certificates in your BizTalk Server implementation, you must specify an account that is in the Windows 2000 Administrators group on the local computer. To configure certificates for the S/MIME components by using BizTalk Messaging Manager, you must also log on using an account that is in the local Windows 2000 Administrators group.
  8. Click Next.

  9. On the Ready to Install the Program page, click Install.

    The BizTalk Server 2002 installation procedure might take several minutes.

  10. When the Welcome to the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard page appears, click Next.

    During BizTalk Server 2002 database setup, you are prompted for SQL Server computer and database information necessary to configure the BizTalk Messaging Management, Tracking, and Shared Queue databases.

    Caution

    • Do not change the code, such as stored procedures or triggers, in the BizTalk Messaging Management, Tracking, and Shared Queue databases. Do not access the databases directly. Do not directly call the stored procedures. Make all changes to the databases by using the methods and properties of the BizTalk Messaging Configuration object model. Making changes directly to the databases bypasses many constraints enforced by the BizTalk Messaging Configuration object model and will either cause the server to function incorrectly or corrupt the database.
  11. On the Configure a BizTalk Messaging Management Database page, accept the default, Create a new BizTalk Messaging Management database, or click Select an existing database and type a server name in the appropriate text box.

    Important

    • If you are installing BizTalk Server 2002 on a computer that is running Microsoft Windows 2000 Professional, the server name you must specify is the name of the computer where you installed Microsoft SQL Server 7.0 or Microsoft SQL Server 2000.

    • To create a new database with the same name as an existing database on the same server, it is recommended that you manually delete the database content. For more information about deleting database content, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online. BizTalk Server setup only verifies whether a stored procedure required by the database exists, rather than verifying whether all the variables required by the database exist. If a stored procedure exists, BizTalk Server setup does not modify the database. If the stored procedure does not exist, BizTalk Server setup deletes the database. Then it reinitializes the BizTalk Messaging Management database tables. This information is also true for the Shared Queue and Tracking databases.

    • If you are setting up more than one BizTalk Server installation and want to centrally manage the BizTalk Messaging Management database, it is highly recommended that you review information about changing the BizTalk Messaging Management database. For more information, see Changing the BizTalk Messaging Management database.
  12. Click Next.

  13. On the Configure a BizTalk Server Group page, type the name that you want to use as your BizTalk Server group in the Group name box or accept the default (BizTalk Server Group), and then click Next.

    If you have set up other BizTalk Server groups you can also click Select an existing BizTalk Server group and select a name from the Group Name list.

    Important

    • The group name cannot contain the following characters: `~ ! @ # $ % ^ & * ( ) + = [ ] { } | ; \ " '< > , . ?

    • All servers within a group must have the same version and language of BizTalk Server installed. If there are servers with different versions of BizTalk Server (BizTalk Server 2000, BizTalk Server 2000 SP1, BizTalk Server 2002 Enterprise Edition, or a different language version of BizTalk Server) installed within a group, the databases will not function properly.
  14. On the Configure a Tracking Database page, repeat the procedure in step 11 and click Next.

  15. On the Configure a Shared Queue Database page, repeat the procedure in step 11 and click Next.

  16. On the Verify BizTalk Server Group page, verify that the information in the BizTalk Server group properties box is correct and click Next.

  17. On the final page of the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard, click Finish to complete the configuration of the BizTalk Messaging Management, Tracking, and Shared Queue databases.

  18. On the Welcome to the Microsoft BizTalk Server 2002 Orchestration Persistence Database Setup Wizard page, click Next to install the Orchestration Persistence database.

    Note

    • If you click Cancel, BizTalk Server 2002 is installed, but the Orchestration Persistence database and the Data Source Name (DSN) are not installed. You can install the database and the DSN later. For more information, see Create a new persistence database, Manage Other COM+ Applications That Host XLANG Schedules, and Configure a COM+ application to host XLANG schedules.
  19. On the Configure a default Orchestration Persistence Database page, accept the default, Create a new default Orchestration Persistence database, or click Select an existing database and then choose a SQL Server computer name and type database information in the appropriate text boxes.

    Important

    • If you select Create a new default Orchestration Persistence database and choose a database with the same name, on the same server, as an existing database, BizTalk Server setup deletes everything in the database. BizTalk Server setup then reinitializes the Orchestration Persistence database tables.

    • If you are installing BizTalk Server 2002 on a computer that is running Windows 2000 Professional, the Server name you specify must be the name of the computer where you installed SQL Server.

    Notes

    • The Orchestration Persistence database is created based on the current user log-on identity.

    • To use SQL Server remotely, you must have the appropriate permissions set for the Orchestration Persistence database. If you have not reconfigured the identity for the XLANG Scheduler Engine, permissions will be granted to the user who was logged on during installation of BizTalk Server 2002. If you have reconfigured the identity for the XLANG Scheduler Engine to match a service account you created or another unique user account, you must set SQL permissions to match the reconfigured identity.
  20. Click Finish.

  21. On the final page of the Microsoft BizTalk Server 2002 Installation Wizard, click View Readme to read important, late-breaking information about BizTalk Server 2002, and then click Finish.

Caution

  • Do not change the impersonation level for any COM+ application. By default, it is set to Impersonate. Changing this security property to Anonymous, Identify, or Delegate can cause problems during installation.

  • After BizTalk Server 2002 is installed on your computer you cannot change the computer name. BizTalk Server 2002 uses the computer name internally; if you change the computer name, BizTalk Server 2002 detects a different name and generates an error message. If you need to rename the computer, uninstall BizTalk Server, rename the computer, and then re-install BizTalk Server.

Important

  • If SQL Server is running on a remote computer, you will need to specify that the SQL Server login account has permissions to access the BizTalk Messaging Management, Shared Queue, and Tracking databases. For more information, see SQL Server and BizTalk Server 2002 Database Interactions.

Note

  • To dramatically increase the performance of BizTalk Orchestration Services, in Windows Explorer, browse to Program Files\Common Files\System\ado and double-click adofre15.reg. In the confirmation dialog box, click Yes, and then click OK. This procedure changes the Microsoft® ActiveX® Data Objects (ADO) threading model from "Apartment threaded" to "Both" and might affect other applications that use ADO. Any provider that is not thread safe cannot be used.

The following procedures should be completed after installation:

  • Avoid unnecessary disk space allocation

  • Start the World Wide Web Publishing Service

  • Configuring BizTalk Document Tracking


Avoid unnecessary disk space allocation

  1. On the Start menu, point to Programs, point to Microsoft SQL Server 7.0 or Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand <server name>, and expand Databases.

  3. Right-click the BizTalk Messaging Management database and click Properties.

    The BizTalk Messaging Management database properties dialog box appears.

  4. Click the Options tab.

  5. In the Settings area, select the Truncate log on checkpoint and Auto shrink check boxes and click OK.

    Note

    • If you have Microsoft SQL Server 2000 installed, select the Auto shrink check box and change the Recovery Model to Simple.
  6. Repeat steps 3 through 5 for the Tracking and Shared Queue databases.

Note

  • During setup, the BizTalk Messaging Management database object name defaults to InterchangeBTM; the Tracking database object name defaults to InterchangeDTA; and the Shared Queue database object name defaults to InterchangeSQ. You might have renamed these default database object names during setup.

Important

  • BizTalk Messaging Manager will not run unless the World Wide Web Publishing Service is running. For more information about the World Wide Web Publishing Service, see Start the World Wide Web Publishing Service.


Start the World Wide Web Publishing Service

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, click Services (Local).

  3. In the details pane, right-click World Wide Web Publishing Service and click Start.


Configuring BizTalk Document Tracking

When BizTalk Document Tracking is installed from the BizTalk Server 2002 compact disc, a shortcut is created on the local computer, in the program group for Microsoft BizTalk Server 2002, to access the BizTalk Document Tracking Web application. However, when the BizTalk Document Tracking Web application is accessed from a remote computer, you must manually create a shortcut or a favorite for later access to the Web application. In either case, to prevent the display of security warning dialog boxes, you must manually configure your browser's settings to trust the Web application.

Configure Internet Explorer security settings

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Document Tracking.

    Notes

    • If you created a favorite in Microsoft Internet Explorer, you can open the BizTalk Document Tracking Web application from Internet Explorer.

    • If you do not have Windows Common Controls and the BizTalk Document Tracking control installed on your computer, you are prompted to install the components. For more information, see Open BizTalk Document Tracking for the first time.
  2. Copy the location of the BizTalk Document Tracking server from the address bar in Internet Explorer to the Clipboard.

  3. On the Tools menu, click Internet Options.

    The Internet Options dialog box appears.

  4. On the Security tab, click Trusted Sites and click Sites.

    The Trusted Sites dialog box appears.

  5. In the Add this Web site to the zone box, paste the location of the BizTalk Document Tracking server from the Clipboard.

  6. Clear the Require server verification (https:) for all sites in this zone check box.

  7. Click Add and click OK twice to close the dialog boxes.


Tools Installation

A Microsoft BizTalk Server 2002 tools installation enables you to install only:

  • BizTalk Orchestration Designer

  • BizTalk Editor

  • BizTalk Mapper

  • BizTalk Server Administration Microsoft Management Console (MMC) snap-in

  • BizTalk Server 2002 Help

The BizTalk Server 2002 parser, serializer, correlation, and run-time binaries are not installed.

Perform a tools installation of BizTalk Server 2002

  1. Insert the Microsoft BizTalk Server 2002 compact disc into the CD-ROM drive to start the Installation Wizard. The Installation Wizard guides you through the steps necessary to install BizTalk Server 2002. Observe the requirements listed in the following steps.

  2. On the Customer Information page, type your name in the User name box, type the name of your company in the Organization box, and then click Next.

  3. On the Destination Folder page, click Next to install BizTalk Server 2002 tools to the default location: C:\Program Files\Microsoft BizTalk Server, or click Change to select another location.

  4. On the Setup Type page, click Tools and click Next.

  5. On the Ready to Install the Program page, click Install.

  6. On the final page of the Microsoft BizTalk Server 2002 Installation Wizard, click View Readme to read important, late-breaking information about this release of BizTalk Server 2002.

  7. Click Finish to complete the installation process.


Custom Installation

A custom Microsoft BizTalk Server 2002 installation enables you to install all the features of BizTalk Server 2002 or only those features that you want.

Note

  • If you want to install the server components of BizTalk Server 2002, you must first install Microsoft SQL Server. For more information, see SQL Server Prerequisites and Installation Requirements.

Caution

  • Do not install the BizTalk Messaging Manager tool, Internet Information Services (IIS), and the Biztalk Server configuration database on three separate computers. This type of configuration causes authentication problems.

Perform a custom installation of BizTalk Server 2002

  1. Insert the Microsoft BizTalk Server 2002 compact disc into the CD-ROM drive to start the Installation Wizard. The Installation Wizard guides you through the steps necessary to install BizTalk Server 2002. Observe the requirements listed in the following steps.

  2. On the Customer Information page, type your name in the User name box, type the name of your company in the Organization box, then click Next.

  3. On the Destination Folder page, click Next to install BizTalk Server 2002 to the default location: C:\Program Files\Microsoft BizTalk Server, or click Change to select another location.

  4. On the Setup Type page, click Custom and click Next.

  5. On the Custom Setup page, follow the on-screen instructions to select the BizTalk Server 2002 components that you want to install.

    To perform a different type of installation, click Back. Otherwise, click Next. Additional pages appear on which you provide additional information, depending on the installation components that you have selected.

  6. On the Ready to Install the Program page, click Install.

    The BizTalk Server 2002 custom installation procedure might take a few minutes.

  7. On the final page of the Microsoft BizTalk Server 2002 Installation Wizard, click View Readme to read important, late-breaking information about this release of Microsoft BizTalk Server 2002.

  8. Click Finish to complete the installation process.

Important

  • BizTalk Messaging Manager will not run unless the World Wide Web Publishing Service is running. For more information about the World Wide Web Publishing Service, see Start the World Wide Web Publishing Service.

  • To dramatically increase the performance of BizTalk Orchestration Services, in Windows Explorer, browse to Program Files\Common Files\System\ado and double-click adofre15.reg. In the confirmation dialog box, click Yes, and then click OK. This procedure changes the Microsoft ActiveX Data Objects (ADO) threading model from "Apartment threaded" to "Both" and might affect other applications that use ADO.

  • To avoid unnecessary disk space allocation, use the Truncate log on checkpoint and Auto shrink features of Microsoft SQL Server. Otherwise, the SQL Server logs can consume large amounts of disk space. For more information, see Avoid unnecessary disk space allocation.


Upgrade Installation

You can use the following section to upgrade to Microsoft BizTalk Server 2002 services, tools, and samples.

Preliminary Setup

  • Before upgrading to BizTalk Server 2002, it is recommended that you do a full backup of your current system.

  • Before upgrading to BizTalk Server 2002, it is recommended that you stop the IISAdmin service. If this is not done, it is possible that two DLLs (MscsCore.dll and MSCSAspHelp.dll) will not be present after the upgrade. If that situation occurs, locate the two dynamic-link library (DLL) files on the BizTalk Server 2002 CD, copy them to the Program Files\Common Files directory, and register the DLLs.

  • You must remove all previous beta versions of Microsoft BizTalk Server before you upgrade to BizTalk Server 2002.

  • BizTalk Server 2002 uses Windows Authentication to access the BizTalk Messaging Management, Shared Queue, and Tracking databases and the BizTalk Document Tracking Web application. Verify that the SQL Server authentication mode is set to Windows before installing BizTalk Server 2002. For more information, see Set SQL authentication mode for SQL Server 2000. If SQL Server is installed on a remote computer, verify that the account you are using is a member of the SQL Server Administrators group. For more information, see SQL Server and BizTalk Server 2002 Database Interactions.

Caution

  • All existing BizTalk Server product files will be removed during the upgrade process, and the configuration of BizTalk Server 2000 Services and COM+ packages will be lost when you upgrade to BizTalk Server 2002.

Important

  • BizTalk Server 2002 requires Microsoft XML Parser (MSXML) version 3.0 with Service Pack 1 (SP1). This release of BizTalk Server 2002 automatically installs MSXML 3.0 SP1. Using BizTalk Server 2002 with other versions of MSXML might produce unpredictable results. If a side-by-side installation of MSXML 3.0 and 4.0 (or later) is necessary, you must uninstall MSXML 4.0 before installing BizTalk Server 2002, and then reinstall MSXML 4.0 after BizTalk Server has been installed.

Perform an upgrade installation of BizTalk Server 2002

  1. Insert the Microsoft BizTalk Server 2002 compact disc into the CD-ROM drive to start the Installation Wizard. The Installation Wizard guides you through the steps necessary to upgrade to BizTalk Server 2002. Observe the requirements listed in the following steps.

  2. On the Customer Information page, type your name in the User name box, type the name of your company in the Organization box, and then click Next.

  3. On the Destination Folder page, click Next to upgrade the BizTalk Server installation located in the default directory.

  4. On the Setup Type page, click Complete, Tools, or Custom and click Next.

    Note

    • All existing BizTalk Server files will be removed during the upgrade process. Only the features that you select will be installed.
  5. On the Configure BizTalk Server Administrative Access page, accept the default group name, BizTalk Server Administrators, or type the group name that you want to use in the Group name box.

    Important

    • Do not rename this group without also modifying the value of "AdminGroupName" in the Windows registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\
      BizTalk Server\1.0\NTGroups      . BizTalk Server 2002 uses this registry key to find the group.

    Note

    • To create a group name, adhere to the following group naming restrictions:

      The group name must be different from any other group or user name on this computer.

      The group name cannot contain the following characters: `~ ! @ # $ % ^ & * ( ) + = [ ] { } | \\ ;\" '< > , . ?

      The group name cannot consist solely of periods (.) or spaces.

  6. On the Microsoft BizTalk Server Service Log On Properties page, accept the default setting This account to specify a service account. This is the account that the BizTalk Messaging Service will run under. This account must have access to SQL Server for BizTalk Messaging to run properly. Type a valid password in the Password box.

    If you do not want BizTalk Services to automatically start when setup completes, clear the Start service after setup completes check box. The BizTalk Server messaging services will not automatically start.

    Notes

    • BizTalk Server setup will grant Log on as a service and Act as part of the operating system rights to the account specified on the Microsoft BizTalk Server Service Log On Properties page.

    • If you select This account, and intend to use public or private key certificates in your BizTalk Server implementation, you must specify an account that is in the Windows 2000 Administrators group on the local computer. To configure certificates for the S/MIME components by using BizTalk Messaging Manager, you must also log on using an account that is in the local Windows 2000 Administrators group.
  7. On the Ready to Install the Program page, click Install.

  8. When the Welcome to the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard page appears, click Next.

  9. On the Configure a BizTalk Messaging Management Database page, click Select an existing database or Create a new BizTalk Messaging Management database.

    Notes

    • The BizTalk Messaging Management (InterchangeBTM), Tracking (InterchangeDTA), and Shared Queue (InterchangeSQ) databases are not removed during the upgrade process. If you choose to create a new database you will need to change the database names.

    • If you choose to keep your existing databases, you will be prompted to confirm that you want to upgrade the schema and stored procedures before installation will continue. The existing database schemas and stored procedures will not be compatible with BizTalk Server 2002. Click Yes to continue.
  10. On the Configure a BizTalk Server Group page, type the name that you want to use as your BizTalk Server group in the Group name box or accept the default (BizTalk Server Group), and then click Next.

    Important

    • All servers within a group must have the same version and language of BizTalk Server installed. If there are servers with different versions of BizTalk Server (BizTalk Server 2000, BizTalk Server 2000 SP1, BizTalk Server 2002 Enterprise Edition, or a different language version of BizTalk Server) installed within a group, the databases will not function properly.
  11. On the Configure a Tracking Database page, and on the Configure a Shared Queue Database page, repeat the procedure in step 9 and click Next to continue.

  12. On the Verify BizTalk Server Group page, verify that the information in the BizTalk Server group properties box is correct and click Next.

  13. On the final page of the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard, click Finish to complete the configuration of the BizTalk Messaging Management, Tracking, and Shared Queue databases.

  14. On the Welcome to the Microsoft BizTalk Server 2002 Orchestration Persistence Database Setup Wizard page, click Next to install the Orchestration Persistence database.

  15. On the Configure a default Orchestration Persistence Database page, click Select an existing database or Create a new BizTalk Messaging Management database.

  16. Click Finish to complete the upgrade process.

Caution

  • After BizTalk Server 2002 is installed on your computer you cannot change the computer name. BizTalk Server 2002 uses the computer name internally; if you change the computer name, BizTalk Server 2002 detects a different name and generates an error message. If you need to rename the computer, uninstall BizTalk Server, rename the computer, and then re-install BizTalk Server.


Silent Installation

The Microsoft Windows Installer (Msiexec.exe) is an executable program that interprets packages and installs products. Msiexec enables you to specify property values from the command line. This method gives you the ability to install Microsoft BizTalk Server 2002 silently (without constant interaction or prompts). A silent installation of BizTalk Server 2002 is ideal for test scenarios or as part of a large-scale enterprise deployment.

Perform a silent installation of BizTalk Server 2002

  1. On the Start menu, click Run.

  2. In the Open box, type cmd and click OK.

  3. Type the following syntax at the command prompt to install BizTalk Server 2002 silently:
    msiexec /I "\\server\folder\Microsoft BizTalk Server.msi"
/qb /Lv* "C:\Temp\install.log" INSTALLLEVEL=200
ALLUSERS=1
DSNCONFIG="C:\Temp\BizTalkInstall.ini"

Important

  • You must add the ALLUSERS=1 parameter to complete the installation for all users. This parameter also ensures that the services are able to see the registry settings.

  • By default the silent installation process uses a local system account. If SQL Server is on a remote computer, this account must be given permissions to access the computer where SQL Server is installed. Failure to do so will cause the service to fail, and will generate errors when accessing the BizTalk Messaging Management database.

Notes

  • The following command-line options are used to run Msiexec in Step 3:
    • /I is the command line to install or configure a product.

    • /qb is the command line to present a basic user interface (progress bar only).

    • /Lv* produces a log file.

    • INSTALLLEVEL=200 installs the server. If you do not specify the INSTALLLEVEL, the value defaults to 100, which is the tools installation of BizTalk Server 2002.

    • DSNCONFIG="C:\Temp\BizTalkInstall.ini" provides installation information to the setup wizard.

You can specify various options at the command line to set properties for a BizTalk Server 2002 installation. Unspecified properties take on the default values. The properties unique to BizTalk Server 2002 are listed in the following table.

Public property | Value | Description
USERNAME (Built-in installer property) | <name> Default: {LogonUser} | The name of the user performing the installation. Customer Information dialog box; User name edit box.
COMPANYNAME (Built-in installer property) | <organization> Default: {LogonCompany} | The organization name for the user performing the installation. Customer Information dialog box; Organization edit box.
INSTALLLEVEL (Built-in installer property) | <install level> Default: 100 | The feature installation level. For BizTalk Server 2002 setup, 100=Client and 200=Server setup type.
INSTALLDIR (Built-in installer property) | <install path> Default: "{ProgramFiles} \Microsoft BizTalk Server" | The destination folder for the installation.
BTS_GROUP_NAME (Complete installation only) | <Group Name> Default: "BizTalk Server Administrators" | The name of the BizTalk Server 2002 Windows NT® group. ConfigAdminGroup dialog box; Group name edit box.
BTS_GROUP_DESCRIPTION (Complete installation only) | <Group Description> Default: "Members can fully administer Microsoft BizTalk Server" | The description of the BizTalk Server 2002 Windows NT group. ConfigAdminGroup dialog box; Group description edit box.
BTS_USERNAME (Complete installation only) | <username> Default: "" | The logon DOMAIN\name for the BizTalk Server 2002 service. ConfigServiceLogon dialog box; User name edit box.
BTS_PASSWORD (Complete installation only) | <password> Default: "" | The logon password for the BizTalk Server 2002 service. ConfigServiceLogon dialog box; Password edit box.
BTS_SERVER (Complete and Tools installations) | <servername> Default: "localhost" | The name of the BizTalk Server to remotely administer. ConfigMgmtDesk dialog box; Server name edit box.
BTS_SDK_SERVER (Complete and Tools installations) | <servername> Default: ""localhost"" | The name of the BizTalk Server to use for DCOM. ConfigSDK dialog box; Server name edit box.
DSNCONFIG (Initialization file) | <pathname> Default: "" | The path of the initialization file for the BTSsetupDB.exe and XLANGsetupDB.exe Database Setup Wizards to use.

Notes

  • The DSNCONFIG property is required to complete a silent installation of BizTalk Server 2002. The initialization path file listed on the command line is passed to the BTSsetupDB.exe and XLANGsetupDB.exe database setup wizards. Use one of the following command-line values:
    • DSNCONFIG="Full path to .ini file for BTSsetupDB.exe and XLANGsetupDB.exe"

      -Or-

    • BTSSETUPDB.INI="Full path to .ini file for BTSsetupDB.exe" and XLANGSETUPDB.INI="Full path to .ini file for XLANGsetupDB.exe"
  • The database setup wizard processes the contents of the initialization file using these rules:
    • All [sections] and keys= are optional; if a key is absent, the default value as shown in the sample initialization file is used.

    • If the GroupName exists in the specified BizTalk Messaging Management database, the [InterchangeDTA] and the [InterchangeSQ] sections are ignored because the group defines the values.

    • Specified databases are created if they do not already exist on the specified server.
  • The BizTalk Messaging Management database setup and the Orchestration Persistence database setup are mutually independent.

  • Depending on the features you install, setup configures either, neither, or both of the following:
    • BizTalk Messaging Management database. Configured only if the BizTalk Messaging Service and its associated components are installed.

    • Orchestration Persistence database. Configured only if BizTalk Orchestration Services is installed.
  • The following properties are used on the command line:
    • DSNCONFIG. Specifies the location of .ini file to be used by BTSsetupDB.exe and XLANGsetupDB.exe.

      -Or-

      BTSSETUPDB.INI. Specifies the location of .ini file to be used by BTSsetupDB.exe.

    • XLANGSETUPDB.INI. Specifies the location of .ini file to be used by XLANGsetupDB.exe.

Sample initialization file with all [sections], keys=, and default values shown

The following is an example of the format of an .ini file needed to silently install BizTalk Server 2002. These command-line properties are required to perform a first-time installation of BizTalk Server 2002 using Microsoft Windows Installer.

Example SetupDB.ini

;----------------------------------------------------------------------
; SQL Server connection parameters for BizTalk Messaging Management database
; Required section used by BTSsetupDB.exe only.
; Specify new or existing database.
;
[InterchangeBTM]
Server=localhost
Username=sa
Password=
Database=InterchangeBTM

;----------------------------------------------------------------------
; Name for BizTalk Server Group
; Required section used by BTSsetupDB.exe only.
; Specify new or existing server group.
;
[Group]
GroupName=BizTalkGroup

;----------------------------------------------------------------------
; SQL Server connection parameters for BizTalk Tracking database
; Required section used by BTSsetupDB.exe only.
; Optional if existing server group specified.
;
[InterchangeDTA]
Server=localhost
Username=sa
Password=
Database=InterchangeDTA

;----------------------------------------------------------------------
; SQL Server connection parameters for BizTalk Shared Queue database
; Required section used by BTSsetupDB.exe only.
; Optional if existing server group specified.
;
[InterchangeSQ]
Server=localhost
Username=sa
Password=
Database=InterchangeSQ

;----------------------------------------------------------------------
; SQL Server connection parameters for Orchestration database
; Required section used by XLANGsetupDB.exe only.
; Specify new or existing Orchestration database.
;
[Orchestration]
Server=localhost
Database=XLANG

The following table describes the properties and values of the sample BizTalkDB.ini initialization file.

Property | Value | Description
[InterchangeBTM] Server=BIZTALK Log on to this first SQL Server with default user name and password.
Database=BizTalkBTM

Create this BizTalk Messaging Management database if it does not already exist on the server.
[Group] | GroupName=BizTalkServerGroup | The rest of the values are ignored if this group already exists.
[InterchangeDTA] Server=DTA-SERVER Log on to this second SQL Server with default user name and password.
Database=BizTalkDTA

Create this Tracking database if it does not already exist on the server.
[InterchangeSQ] Server=SQ-SERVER Log on to this third SQL Server with default user name and password.
Database=BizTalkSQ

Create this Shared Queue database if it does not already exist on the server.
[Orchestration] Server=localhost Log on to this fourth SQL Server with default user name and password.
Database=BizTalkXLANG

Create this Orchestration Persistence database if it does not already exist on the server.

Command-line options of Microsoft Windows Installer

Microsoft Windows Installer (Msiexec.exe) is the program that interprets packages and installs products. It also sets an error level on return that corresponds to the Microsoft® Win32® error codes. The following table describes command-line options for this program that you can use in addition to the properties and values listed previously.

Option | Parameters | Meaning
/I | Package|ProductCode | Installs or configures a product.
/f [p|o|e|d|c|a|u|m|s|v] Package|ProductCode Repairs a product. This option ignores any property values entered on the command line. The default argument list for this option is pecms. This option shares the same argument list as the REINSTALLMODE property.

p - Reinstall only if file is missing.

o - Reinstall if file is missing or if an older version is installed.

e - Reinstall if file is missing or an equal or older version is installed.

d - Reinstall if file is missing or a different version is installed.

c - Reinstall if file is missing or the stored checksum does not match the calculated value. Repairs only files that have msidbFileAttributesChecksum in the Attributes column of the File table.

a - Force all files to be reinstalled.

u - Rewrite all required user-specific registry entries.

m - Rewrite all required computer-specific registry entries.

s - Overwrite all existing shortcuts.

v - Run from source and recache the local package.
/a | Package | Administrative installation option. Installs a product on the network.
/x | Package|ProductCode | Uninstalls a product.
/j [u|m]Package

or

[u|m]Package /t Transform List

or

[u|m]Package /g LanguageID

 Advertises a product. This option ignores any property values entered on the command line.

u - Advertise to the current user.

m - Advertise to all users of the computer.

t - Apply transform to advertised package.

g - Language ID.
/L [i|w|e|a|r|u|c|m|o|p|v|+|!]Logfile Specifies the path to a log file; the flags indicate which information to log.

i - Status messages

w - Nonfatal warnings

e - All error messages

a - Startup of actions

r - Action-specific records

u - User requests

c - Initial UI parameters

m - Out-of-memory or fatal exit information

o - Out-of-disk-space messages

p - Terminal properties

v - Verbose output

+ - Append to existing file

! - Flush each line to the log

"*" - Wildcard; log all information except the v option. To include the v option, specify "/l*v".
/m filename Generates a Systems Management Server (SMS) status .mif file. Must be used with the install (-i), remove (-x), administrative installation (-a), or reinstall (-f) option. The Ismif32.dll is installed as part of SMS and must be on the path.

The fields of the status .mif file are filled with the following information:

  • Manufacturer - Author

  • Product - Revision number

  • Version - Subject

  • Locale - Template

  • Serial Number - Not set

  • Installation - Set by Ismif32.dll to "DateTime"

  • InstallStatus - "Success" or "Failed"

  • Description - Error messages in the following order: 1) Error messages generated by installer; 2) Resource from Msi.dll if installation could not commence or user exits; 3) System error message file; 4) Formatted message: "Installer error %i", where %i is the error returned from Msi.dll.
/p PatchPackage Applies a patch. To apply a patch to an installed administrative image, you must combine options as follows:

/p <PatchPackage> /a <Package>
/q n|b|r|f Sets the user interface (UI) level.

q, qn - No UI.

qb - Basic UI.

qr - Reduced UI with a modal dialog box displayed at the end of the installation.

qf - Full UI with a modal dialog box displayed at the end.

qn+ - No UI except for a modal dialog box displayed at the end.

qb+ - Basic UI with a modal dialog box displayed at the end. The modal dialog box is not displayed if the user cancels the installation.

qb- - Basic UI with no modal dialog boxes. /qb+- is not a supported UI level.
/?

or

/h

 Displays copyright information for the Windows Installer.
/y module Calls the system API DllRegisterServer to self-register modules passed in on the command line. For example, msiexec /y my_file.dll.

This option is used only for registry information that cannot be added using the registry tables of the .msi file.
/z module Calls the system API DllUnRegisterServer to unregister modules passed in on the command line. For example, msiexec /z my_file.dll.

This option is used only for registry information that cannot be removed using the registry tables of the .msi file.

Note

  • In the preceding table:
    • The options /i, /x, /f[p|o|e|d|c|a|u|m|s|v], /j[u|m], /a, /p, /y, and /z should not be used together. The one exception to this rule is that patching an administrative installation requires using both /p and /a.

    • The options /t and /g should be used only with /j.

    • The options /l and /q can be used with /i, /x, /f[p|o|e|d|c|a|u|m|s|v], /j[u|m], /a, and /p.

Syntax rules for properties and values

Only public properties can be modified using the command line. All property names on the command line are interpreted as uppercase, but the value retains case sensitivity. If you type MyProperty at a command line, the installer overrides the value of MYPROPERTY and not the value of MyProperty in the Property table. To install a product with PROPERTY set to VALUE, use the following syntax on the command line. You can put the property anywhere except between an option and its argument.

Correct syntax:

msiexec /i A:\Example.msi PROPERTY=VALUE

Incorrect syntax:

msiexec /i PROPERTY=VALUE A:\Example.msi

Property values that are literal strings must be enclosed in quotation marks. Include any white spaces in the string between these marks.

msiexec /i A:\Example.msi PROPERTY="Embedded White Space"

To clear a public property using the command line, set its value to an empty string.

msiexec /i A:\Example.msi PROPERTY=""

For sections of text set apart by literal quotation marks, enclose the section with a second pair of quotation marks.

msiexec /i A:\Example.msi PROPERTY="Embedded ""Quotes"" White Space"

The following is an example of a complicated command line.

msiexec /i testdb.msi INSTALLLEVEL=3 /l* msi.log COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""

The following example illustrates advertisement options. Switches are not case sensitive.

msiexec /JM msisample.msi /T transform.mst /G langid /LIME logfile.txt

For more information about Microsoft Windows Installer, go to the Microsoft® MSDN® Web site (msdn.microsoft.com/downloads/).


Removing BizTalk Server 2002

Use the Microsoft Windows 2000 Add/Remove Programs utility to remove Microsoft BizTalk Server 2002.

Notes

  • The BizTalk Server uninstall process will not remove SQL databases or the maps and schemas that have been stored in WebDAV. Any files that you have added to the BizTalk Server directory will also be preserved.

  • In a cluster environment, before uninstalling BizTalk Server 2002, ensure that the computer has network connectivity to the computer hosting the BizTalk Server databases, and all other BizTalk Servers in the group. Should errors occur while uninstalling, you might need to manually delete the following COM+ applications:
    • BTS Interchange

    • BTS Internal Utilities

    • XLANG Scheduler

    • XLANG Persistence Helper

Remove BizTalk Server 2002

  1. On the Start menu, point to Settings and click Control Panel.

  2. Click Add/Remove Programs.

    The Add/Remove Programs dialog box appears.

  3. Click Microsoft BizTalk Server 2002 and click Remove.

  4. Follow the on-screen instructions and click Yes when prompted to remove BizTalk Server 2002.


Understanding Security

Microsoft® BizTalk™ Server 2002 enables businesses to securely exchange data with trading partners by taking advantage of the security features offered through Microsoft Windows® 2000 security.

The Windows 2000 security features used by BizTalk Server include the following:

  • Windows Account Security and Local Policies

  • Integrated Windows and Microsoft SQL Server™ Logon Security

  • Microsoft Component Services Security and Roles

  • Public-key infrastructure (PKI)

  • CryptoAPI

  • Smart cards

  • Kerberos protocol

BizTalk Server controls access to tools (for example, the BizTalk Server Administration console), APIs (for example, Windows Management Instrumentation), COM+ applications, and other resources, by granting access to those resources to specific user accounts. One way privileges are granted to user accounts is by adding those accounts to the Windows groups created by BizTalk Server. When BizTalk Server is installed, it creates two local Windows groups: BizTalk Server Administrators and BizTalk Server Report Users. Adding user accounts to these groups on the BizTalk Server computers grants those accounts certain privileges on BizTalk Server. For example, you must be logged on using an account that is in the BizTalk Server Administrators group to open BizTalk Messaging Manager or the BizTalk Server Administration console on that computer.

In addition, specific permissions might need to be granted at the operating system level to perform certain tasks. For example, you must grant the BizTalk Server Messaging service account full privileges on the BizTalk Server Windows Management Instrumentation (WMI) namespace for it to generate Suspended queue WMI events.

BizTalk Server controls access to SQL Server by leveraging SQL Server integrated security. With SQL Server integrated security, SQL Server relies on Windows Authentication to grant access to SQL Resources. By default, all accounts that need to access one of the SQL Server databases required by BizTalk Server must be given a SQL Server integrated logon and be granted access to the database. For more information, see SQL Server and BizTalk Server 2002 Database Interactions . With the exception of the connections to the Orchestration Persistence database, database access through BizTalk Server tools and run-time services cannot be configured to use anything other than integrated security.

Component Services, one of the Administrative Tools available in Windows 2000, offers comprehensive component functionality, such as automatic transaction support for data-integrity protection and simple, but powerful, role-based security.

BizTalk Server controls security between trading partners through the use of PKIs and Secure Multipurpose Internet Mail Extensions (S/MIME). By exchanging public and private key certificates, trading partners can authenticate each other and encrypt communications through the use of x.509 digitally signed messages and S/MIME (or custom encryption using their own components). For more information, see Certificates Overview.

Because BizTalk Server takes advantage of Windows 2000 Secure Sockets Layer (SSL), Web pages can be created and used by trading partners to securely exchange data using the Internet. SSL, which is implemented in Internet Information Services (IIS), is a protocol designed to provide privacy between a Web client and a Web server. The protocol begins with a handshake phase that negotiates an encryption algorithm, checks the keys (public and private), and authenticates the server to the client. Once the handshake is complete and application data transmission begins, all data is encrypted using the session keys negotiated during the handshake. Support for open PKI standards and secure protocols, such as IPSec, L2TP, SSL/TLS, and S/MIME, enables a network to be extended to suppliers and partners quickly, while protecting against impostors, data theft, or malicious hackers.

The following topics are covered in this section:

  • Logon Properties

  • Local Policies

  • Security Guidelines

  • BizTalk Server Administrators Group

  • BizTalk Messaging Service

  • BizTalk Server Interchange Application Security

  • Security for Applications That Host XLANG Schedule Instances

  • BizTalk Server Report Users Group

  • Transport Services

  • Certificates Overview

  • CryptoAPI

  • Collaboration Data Objects

  • Configuring Firewalls

Related Topic

Administration Privileges


Logon Properties

Logon properties are the initial layer of security for BizTalk Server 2002. These properties control a user's ability to log on to a specific computer or domain and to perform specific tasks on that computer or domain. Logon properties require a user to provide a user name and password prior to accessing resources, such as a file share or message queue. Messages received through HTTP and SMTP also use logon properties to ensure security. For example, an ASP page accessed through HTTP could require a user to enter a user name and password prior to displaying the contents of the Web page.

BizTalk Server can use Internet Information Services (IIS) and ASP pages to receive documents. ASP pages (actually the code behind the pages) provide a layer of security for BizTalk Server by verifying signatures from Secure Sockets Layer (SSL) and maximizing additional security, such as certificates, through IIS. For more information about IIS security, see "Internet Information Services" in Windows 2000 Help.

Related Topic

Administration Privileges


Local Policies

Local Policies, which is part of the Local Security Settings console, determine the security options for a user or service account. Local policies are based on the computer a user is logged into, and the rights the user has on that particular computer. To set local policies, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, double-click Local Security Policy, and then expand the Local Policies folder.

Local policies define the privileges and rights for BizTalk Server 2002 users. Local Policies can be used to configure:

  • Audit Policy. Determines which security events are logged into the Security log on the computer (successful attempts, failed attempts, or both). (The Security log is part of Event Viewer.)

  • User Rights Assignment. Determines which users or groups have logon or task privileges on the computer.

  • Security Options. Enables or disables security settings for the computer, such as digital signing of data, Administrator and Guest account names, floppy drive and CD-ROM access, driver installation, and logon prompts.

Other policies in the Local Security Settings console can be configured to maintain the integrity of your data. For example, Account Policies can be used to configure:

  • Password Policy. For local user accounts, determines settings for passwords, such as enforcement and lifetimes.

  • Account Lockout Policy. For local user accounts, determines when and for whom an account will be locked out of the system.

Important

  • Local policies, by definition, are local to a computer. When these settings are imported to a Group Policy object in Active Directory, they will affect the local security settings of any computer accounts to which that Group Policy object is applied. Therefore, it is important to note the order of precedence for security policies. Security policies associated with Group Policy (Organizational Units) override policies established at the local level. Policies from the domain override locally defined policies. In either case, user account rights may no longer apply if there is a local policy setting that overrides those privileges. This is important because the behavior of Microsoft Windows 2000 can be quite different from the behavior in Microsoft Windows NT. For example, when password policies are configured for the Domain group policy (as they are by default), they affect every computer in that domain. This means that the local account databases (on individual workstations) in the domain have the same password policy as the domain itself.

Note

  • Do not set Local Policies for public keys. Public keys provide security protection for BizTalk Server. Public keys are a component of certificates that are used to encrypt and decrypt data. By adding additional policies to a public key, BizTalk Server will not be able to use the associated certificate.

Related Topic

Administration Privileges


Security Guidelines

BizTalk Server 2002 uses integrated Windows NT security to access SQL Server, rather than using SQL Server credentials. This means that BizTalk Server uses the credentials of the user currently logged on to determine SQL Server privileges. Therefore, when installing and configuring BizTalk Server Administration components, there are some security issues that need to be considered as follows:

BizTalk Server feature | Security guidelines
BizTalk Server Administration
  • User must be a member of the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.

  • User must have full access to the Shared Queue and BizTalk Messaging Management databases and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.
BizTalk Messaging Manager
  • User must be a member of the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.

  • User must have full access to the Shared Queue and BizTalk Messaging Management databases and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.
BizTalk Messaging Configuration Object Model
  • User must be a member of the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.

  • User must have full access to the Shared Queue and BizTalk Messaging Management databases and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.
BizTalk Messaging Service
  • BizTalk Server Messaging service account must have been assigned Log on as a service security policies.

  • BizTalk Server Messaging service account must be granted full permission on the Root\MicrosoftBizTalkServer Windows Management Instrumentation (WMI) namespace. For more information, see Grant WMI namespace permission to a Windows account.

  • User must have full access to the Shared Queue, Tracking, and BizTalk Messaging Management databases and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.

  • If a user name/password have been specified for any receive function, the Log on locally and Act as part of the operating system security policies must be granted to the receive function user account.

  • If an HTTP receive function(s) has been created, the associated BizTalk ISAPI Extension(s) will require additional security configuration. For more information, see Configure access privileges based on IIS protection level.
BizTalk Server Interchange Application (COM+)
  • Application identity account must be granted full permission on the Root\MicrosoftBizTalkServer WMI namespace. For more information, see Grant WMI namespace permission to a Windows account.

  • Application identity account must have full access to the Shared Queue, Tracking, and BizTalk Messaging Management databases and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.
BizTalk Server Document Tracking UI
  • User account must have full access to the Tracking database and be a member of the db_owner role for those databases. For more information, see Create a SQL login and grant it database access.

  • User account must be a member of the BizTalk Server Report Users group.
XLANG Scheduler Application (COM+)
  • If the data source name (DSN) for accessing the Orchestration Persistence database is configured with Windows Authentication (as it is by default), then the credential of the user who interacts with an XLANG schedule instance must have full access to the Orchestration Persistence database and be a member of the db_owner role for that database. For more information, see Create a SQL login and grant it database access.

  • If the DSN is configured with SQL Authentication, the SQL login used must have full access to the Orchestration Persistence database and be a member of the db_owner role for that database. For more information, see Create a SQL login and grant it database access.

  • The user who interacts with an XLANG schedule instance must a member of the XLANG Schedule User role under the COM+ configuration of that BizTalk XLANG Scheduler Application. For more information, see Security for Applications That Host XLANG Schedule Instances.
BizTalk SEED Wizard
  • User must be a member of the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.

  • User must have full access to the BizTalk Messaging Management database and be a member of the db_owner role for that database. For more information, see Create a SQL login and grant it database access.
BizTalk Deployment using Application Center 2000
  • User must be a member of the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.

  • User must have full access to the BizTalk Messaging Management database and be a member of the db_owner role for that database. For more information, see Create a SQL login and grant it database access.
XLANG Monitor
  • User must be a member of the XLANG Schedule Creator role for the XLANG Schedule and for the COM+ applications that host XLANG schedules. For more information, see Add a role to the BizTalk Server Interchange Application; but, if you perform this procedure, you need to replace the Interchange application with the COM+ application that hosts XLANG schedules.
Application Designer | No security requirements.
BizTalk Editor and BizTalk Mapper | No security requirements.

The following procedures are covered in this section:

  • Create a SQL login and grant it database access

  • Grant WMI namespace permission to a Windows account


Create a SQL login and grant it database access

For an account used by BizTalk Server to be able to access the SQL Server databases, it is necessary to explicitly grant access to this account.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the individual server that contains the BizTalk Messaging Management and Shared Queue databases.

  3. Expand the Security folder, right-click Logins, and then click New Login.

    The SQL Server Login Properties - New Login page appears.

  4. In the Name box, enter the name of the Windows account you want to create a SQL login for.

  5. In the Authentication area, make sure Windows Authentication is selected, and enter the domain of the Windows account. Click OK.

  6. Click the Database Access tab, select the Permit box for the database you want to change the permission for, and then select db_owner from the Permit in Database Role list.

  7. Select the Permit box for the Shared Queue database, select db_owner from the Permit in Database Role list, and then click OK.


Grant WMI namespace permission to a Windows account

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and double-click Computer Management.

    The Computer Management console appears.

  2. Expand Services and Applications, right-click WMI Control, and then click Properties.

    The WMI Control Properties dialog box appears.

  3. Click the Security tab, double-click the Root node, and click the MicrosoftBizTalkServer namespace.

  4. Click the Security button.

    The Security for ROOT\MicrosoftBizTalkServer dialog box appears.

  5. Click the Add button.

    The Select Users, Computers, or Groups dialog box appears.

  6. Type the name of the Windows account you want to grant WMI namespace permission and click OK.

  7. Make sure all Permissions are selected as Allow.

  8. Click OK.

  9. Click OK to close the WMI Control Properties dialog box.


BizTalk Server Administrators Group

During installation, BizTalk Server 2002 creates a Windows group on the local computer whose members are granted administrative and other privileges on BizTalk Server. By default, this group is named BizTalk Server Administrators, although the user running setup is allowed to change this name. However, the name cannot be modified after installation. At installation, BizTalk Server adds the built-in local Administrators group and the currently logged on user account to this group.

The primary purpose of the BizTalk Server Administrators group is to control access to tools and application programming interfaces (APIs) provided by BizTalk Server. For more information about which resources require the user to be member of this group, see Security Guidelines.

Note

  • The service account that the BizTalk Messaging Service runs under does not need to be a member of this group for BizTalk Server to function properly.


BizTalk Messaging Service

The BizTalk Messaging Service is a Windows service that provides the substance of the BizTalk Messaging run-time functionality. As a Windows service, the BizTalk Messaging Service runs under its own security context, either as Local System or as a service account created by the user, known as the BizTalk Server Messaging service account. A service account is a Windows user account that has been granted the special privileges of Act as part of the Operating System and Log on as a Service. During setup, BizTalk Server grants these privileges to the account specified by the user for the BizTalk Server Messaging service account. For more information, see Installation Instructions.

The two reasons why you might what to use Local System as opposed to a Windows local or domain service account depends largely on two factors:

  1. SQL Server topology. The BizTalk Server Messaging service account must be granted access to the SQL Server database used by BizTalk Server for it to function. If you are running BizTalk Server on the same computer as the SQL Server databases used by BizTalk Server, then any account can be used. However, if you are using a SQL Server that is on a computer separate from that on which BizTalk Server is running, it might be most convenient to use a Windows domain account for the BizTalk Server Messaging service account. By configuring BizTalk Server to use the same domain account, all BizTalk Servers are granted access to SQL Server in one step by granting access to that one domain account.

  2. Digital certificate usage. If you intend to take advantage of the digital signing and encryption/decryption features of BizTalk Server, the BizTalk Server Messaging service account must be a member of the local Windows Administrators built-in group. This is required in order to access the digital certificate stores on the local computer.

Note

  • The BizTalk Server Messaging service account does not have to be a member of the BizTalk Server Administrators group for BizTalk Server to function properly.


BizTalk Server Interchange Application Security

The COM+ interface used to programmatically submit documents to BizTalk Server 2002 resides in a COM+ application that is created by BizTalk Server during setup, called BizTalk Server Interchange Application. By default, the identity of this application is configured as Interactive User. However, if this is not modified, a user must be logged on whenever programmatic submissions are performed. Obviously, this is unacceptable for most purposes. To configure the BizTalk Server Interchange Application to run under a service account, see Change the application identity for a COM+ application.

Controlling a user's ability to programmatically send work items to BizTalk Server through the IInterchange COM+ interface can be accomplished by properly configuring the BizTalk Server Interchange Application COM+ component. To control a user's ability to programmatically send work items, a role must first be added to the BizTalk Server Interchange Application, then the role must be associated with the Submit and SubmitSync methods, and finally, the user account that you want to grant access to the methods must be added to the role.

The following topics are covered in this section:

  • Add a role to the BizTalk Server Interchange Application

  • Associate a new role with the Submit and SubmitSync methods

Related Topic

Administration Privileges


Add a role to the BizTalk Server Interchange Application

Role memberships need to be created to control the ability of different users to submit work items to the BizTalk Server Interchange Application.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

    The Component Services console appears.

  2. Expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Right-click BizTalk Server Interchange Application and click Properties.

    The BizTalk Server Interchange Application Properties dialog box appears.

  4. Click the Advanced tab and, in the Permission area, clear the Disable changes check box, click OK, and then, in the message dialog box, click Yes.

  5. Repeat step 3.

  6. Click the Security tab and, in the Authorization area, select the Enforce access checks for this application check box.

  7. In the Security level area, click Perform access checks at the process and component level. Security property will be included on the object context. The COM+ security call is available.

  8. Click OK.

  9. In the message dialog box, click Yes.

  10. Expand BizTalk Server Interchange Application.

  11. Double-click the Roles folder, right-click the folder, point to New, and then click Role.

    The Role dialog box appears.

  12. Type a name for the role and click OK.

  13. In the message dialog box, click Yes.

  14. Expand the role you just created, double-click the Users folder, right-click Users, point to New, and then click User.

  15. In the Select Users or Groups box, type the full name of the user you want to add.

  16. When you have finished adding user accounts to the role, click OK.

Note

  • For each user account or group assigned to the role, an icon appears in the Users folder. The new role membership will be activated when the application is started.

Related Topic

Shut down the BizTalk Server Interchange Application


Associate a new role with the Submit and SubmitSync methods

Once a new role for the BizTalk Server Interchange Application has been created, the Submit and SubmitSync methods can be associated with it.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

    The Component Services console appears.

  2. Expand Component Services, expand Computers, expand My Computer, expand COM+ Applications, expand BizTalk Server Interchange Application, expand Components, expand BizTalk.Interchange.1, expand Interfaces, expand IInterchange, and expand Methods.

  3. Right-click Submit and click Properties.

    The Submit Properties dialog box appears.

  4. Click the Security tab.

  5. In the Roles explicitly set for selected item(s) area, select the check box for the role you just created in the Add a role to the BizTalk Server Interchange Application procedure and click OK.

  6. Right-click SubmitSync and click Properties.

    The SubmitSync Properties dialog box appears.

  7. Click the Security tab.

  8. In the Roles explicitly set for selected item(s) area, select the check box for the role you just created in the Add a role to the BizTalk Server Interchange Application procedure and click OK.

Related Topic

Shut down the BizTalk Server Interchange Application


Security for Applications That Host XLANG Schedule Instances

After installing BizTalk Orchestration Services, security levels can be set for the following:

  • Creating new XLANG schedule instances

  • Interacting with existing XLANG schedule instances

  • Administrative functions relating to XLANG schedule instances

  • Applications hosting XLANG schedule instances

Applications that host XLANG schedule instances rely on role-based security, which is an automatic service provided by COM+. Role-based security enables users to construct and enforce an access control policy for COM+ applications. With a flexible and extensible security configuration model, role-based security offers considerable benefits over enforcing all security within components. There are two default COM+ applications, the XLANG Scheduler and the XLANG Scheduler Persistence Helper, which are automatically created when BizTalk Orchestration Services are installed. By default, the identity of these applications is configured as Interactive User. However, if this is not modified, a user must be logged on whenever schedules are invoked or accessed. Obviously, this is unacceptable for most purposes. To configure the BizTalk Server Interchange Application to run under a service account, see Change the application identity for a COM+ application.

The XLANG Scheduler COM+ application has four roles that can be used to ensure the security of schedule instances regardless of the COM+ application in which they run. The four roles are:

  • XLANG Schedule Creator. This role allows specified users to create XLANG schedule instances. For instance, if an administrator wants a user to be able to create an XLANG schedule instance, the administrator must add the user to the membership list for this role. Any user who is not listed as a member of this role and attempts to create an XLANG schedule instance will see an error message indicating that access has been denied. In addition, an entry is generated in the Event Log indicating that access has been denied.

  • XLANG Schedule User. This role allows specified users to interact with XLANG schedule instances. For instance, if an administrator wants a user to be able to interact with a schedule instance, the administrator must add the user to the membership list for this role. Any user who is not listed as a member of this role and attempts to interact with a schedule instance will see an error message indicating that access has been denied. In addition, an entry is generated in the Event Log indicating that access has been denied.

  • XLANG Scheduler Administrator. This role can be used to indicate who has administrative rights to the following tasks:
    • Determining whether a COM+ application is able to act as a host for XLANG schedule instances.

    • Setting the DSN type for a COM+ application that is hosting XLANG schedule instances and setting the state management value for the level of persistence the COM+ application needs to support.

    • Shutting down all XLANG schedule instances.

    • Suspending, resuming, or terminating an XLANG schedule instance.
  • XLANG Scheduler Application. This role is used by the XLANG Scheduler to interact with any COM+ application that a user creates. Therefore, the role must include the same identity that the COM+ application is using to run.

The following topics are covered in this section:

  • Best Practices for Securing COM+ Applications

  • Securing the Orchestration Persistence Database

  • Confirming the Sender's Identity

Related Topic

XLANG Schedules


Best Practices for Securing COM+ Applications

Using roles, an administrator can administratively construct an authorization policy for an application, choosing (down to the method level, if necessary) which users can access which resources. Because all XLANG schedules are hosted in COM+ server applications, access to the installed COM objects can be limited by configuring security properties for various roles.

Important

  • If security properties are added at the component level, individual components, interfaces, and methods based on the role settings at these levels are also limited. For more information about COM+ security, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp), and search on "Security in COM+".

Recommendations for securing COM+ applications

The following recommendations apply primarily to securing deployed applications:

  • Do not configure a COM+ application as an interactive user. COM+ applications that use the interactive user identity can be used only if a user is logged on to the computer where the application resides. If no one is logged on, the COM+ application cannot run. In addition, if a user creates a COM+ application using Interactive User, it will be more difficult to configure access to its persistence database and other resources.

  • Reconfigure the identity for XLANG Scheduler. During setup, the XLANG Scheduler identity is automatically configured as Interactive User. This configuration is suitable for most developers. On production systems, you should change the identity property for the XLANG Scheduler so that the application runs under a unique user account. The identity is used by all messages sent by the XLANG Scheduler.

    Note

    • When using the client for Microsoft Windows 2000 Terminal Services to initiate an XLANG schedule, the COM+ application hosting the XLANG Scheduler Engine must have its identity set to a valid Windows 2000 user or group name. The identity of the COM+ application is set on the Identity tab of the properties dialog box for that application. The identity cannot be set to interactive when using the XLANG Scheduler Engine through a session hosted by Terminal Services.
  • Create a new COM+ application with a unique identity for every application that is hosting XLANG schedule instances. Create a new COM+ application with a unique identity for each business process, such as purchasing, with unique security requirements. This enables individual security levels to be specified for each application. In addition, it safeguards from excessive damage that can be done by unstable application code and makes it easier to audit the operations of individual applications.

  • Install application-specific components into their associated business processes. This protects data and keeps out applications that do not have access to these components, provided the server application is adequately protected.

    Note

    • Each COM+ application must contain at least one component. If an application-specific component is not installed, a placeholder component in the application must be created and installed, or the COM+ application will not be available.
  • Change the membership list of the XLANG Scheduler roles from their defaults to provide added security. When BizTalk Server is installed, the XLANG Scheduler is created and configured with the following roles, shown with their default settings:
    • XLANG Schedule Creator. Membership role defaults to Everyone.

    • XLANG Schedule User. Membership role defaults to Everyone.

    • XLANG Scheduler Administrator. Membership role defaults to Administrators.

    • XLANG Scheduler Application. Membership role defaults to Everyone.

Related Topics

Change the application identity for the default XLANG Scheduler application

Create a COM+ application to host XLANG schedules

XLANG Schedules


Securing the Orchestration Persistence Database

When a COM+ application that hosts XLANG schedule instances is created, a persistence database must be associated with the COM+ application. Therefore, first create a persistence database in Microsoft SQL Server. After creating the database, if the XLANG COM+ application database data source name (DSN) is configured to use integrated security, a user needs to create a SQL login and grant db_owner privileges to the identity account of the COM+ application that will be created later to host XLANG schedule instances. Make sure that the COM+ application has permissions to both create tables and create procedures in the associated persistence database. By default, the interaction between BizTalk Orchestration Services and the default BizTalk Server Orchestration Persistence database is based on the Windows 2000 security model rather than on SQL Server.

Related Topic

Manage the Default XLANG Scheduler Application


Confirming the Sender's Identity

During schedule design, various shapes can be used to describe implementation technologies used to implement a port in a business process. The following shapes describe these technologies:

  • The COM Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received.

  • The Script Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received.

  • The Message Queuing shape represents a technology that is used to implement a port. Message Queuing transport services are used to send or receive messages.

When adding one of the three technologies, a user can require that the sender's identity be confirmed prior to receiving messages. When the sender's identity is required, the identity of the Windows user account (domain\user) of the person who called this component is placed in the _Sender_ field of the message.

For more information about COM components, Windows Script Components, or Message Queuing security for XLANG schedules, see Implement a port by using a COM component, Implement a port by using a Windows Script Component, and Implement a port by using Message Queuing.

Related Topics

Using the COM Component Shape

Using the Message Queuing Shape

Using the Script Component Shape


BizTalk Server Report Users Group

During installation, BizTalk Server 2002 creates a Windows group on the local computer whose members are granted privileges to use the BizTalk Document Tracking user interface and view tracked documents. By default, this group is named BizTalk Server Report Users, although the user running setup is allowed to change this name. However, the name cannot be modified after installation. At installation, BizTalk Server adds the built-in local Administrators group and the currently logged on user account to this group.

Also during installation, BizTalk Server grants access permissions for this group, the local Administrators group, and the currently logged on user account to the file directory in which the Web-based BizTalk Document Tracking user interface resides, that is, \Program Files\Microsoft BizTalk Server\BizTalkTracking.

Users that require access to use the BizTalk Document Tracking user interface and view tracking documents must be in the BizTalk Server Report Users group and must have access to the Tracking database, that is, have a logon in the SQL Server hosting the Tracking database and be a member of the db_owner role for that database.


Transport Services

Microsoft BizTalk Server 2002 supports a core set of transport services. These transport services enable the server to send documents to organizations or applications whether or not the applications are capable of communicating directly with the server by using a Component Object Model (COM) interface. BizTalk Server supports the HTTP, HTTPS, and SMTP network protocols and Message Queuing.

The following topics are covered in this section:

  • HTTP and HTTPS

  • SMTP

  • Message Queuing 2.0

  • File

Related Topics

Select a transport type

Set Transport Properties


HTTP and HTTPS

HTTPS is used to provide strong authentication when using Hypertext Transfer Protocol (HTTP) to gain access to content on the Web. The most common use of Secure Hypertext Transfer Protocol (HTTPS) is to provide an encrypted connection to an authenticated Web server. When clients attempt to establish an HTTPS connection, typically triggered by browsing to a URL beginning with https://, the client and server jointly negotiate a security protocol to use and then exchange authenticating information.

Microsoft Internet Explorer 5 or later supports common secure communication protocols for HTTP transactions, including the following:

  • Transport Layer Security (TLS version 1.0)

  • Secure Sockets Layer (SSL versions 2 and 3)

  • Private Communications Technology (PCT version 1.0)

Each protocol provides both encryption services (for confidentiality of exchanged data) and authentication services (for mutual identification between clients and servers). SSL support, which is provided through the built-in HTTPS transport service, adds server-to-server authentication and transport layer encryption to an interchange.

BizTalk Server and HTTPS can be used to securely exchange data within an organization or with a trading partner by means of HTTP. The following provides specific details regarding how BizTalk Server 2002 uses HTTP and HTTPS to send and receive data:

Send

The HTTP and HTTPS transport services can be used to secure data that is sent to an application or trading partner. Security for these transport services relies on certificates.

For example, prior to sending data over HTTP, a BizTalk Server administrator sends a copy of the client certificate to a trading partner. The trading partner retains a copy of the certificate in the BizTalk store. In the future, the certificate is used to authenticate the trading partner sending data. A unique certificate manager must be created to send or export a certificate to a trading partner.

Receive

To secure data over HTTP, BizTalk Server uses Microsoft Internet Information Services (IIS) and ASP pages. When using HTTPS to connect to IIS, the client and browser negotiate a common protocol to secure the channel. In cases where the server and client have multiple protocols in common, IIS secures the channel with a supported protocol, such as SSL. To secure data that is received by BizTalk Server over HTTP, the process is identical. The ASP page serves as the gateway for sending data to BizTalk Server. If the data is secure, BizTalk Server receives the data provided the ASP code uses the Submit method or the SubmitSync method to make a call.

Related Topics

Select a transport type

Set Transport Properties


SMTP

Simple Mail Transfer Protocol (SMTP) is a protocol for sending e-mail messages between servers. SMTP is a common protocol for sending e-mail over the Internet. An e-mail message can be retrieved with an e-mail client using either Post Office Protocol (POP) or Internet Message Access Protocol (IMAP). In addition, SMTP is used to send messages from a mail client to a mail server. When configuring an e-mail application, both the POP or IMAP server and the SMTP server must be specified.

SMTP can be used to securely exchange data within an organization or with a trading partner. BizTalk Server 2002 uses SMTP to send and receive data using the following methods:

Send

BizTalk Server implements a transport protocol to send data over SMTP. At a minimum, SMTP requires that data be MIME-encoded. This process enables BizTalk Server to identify where a set of data ends and the next set of data begins. However, MIME encoding does not provide security. S/MIME is the secure MIME version. Documents encoded using built-in S/MIME encoding components ensure document integrity, authentication of the sending party, and payload encryption. BizTalk Server creates an S/MIME document with the encrypted message as the body of the document. To add this security layer, a certificate must be associated with the MIME-encoded message. MIME encoding can be specified when messaging ports are created in BizTalk Messaging Manager. This is also where certificates are specified.

Receive

To implement security on the receive side of SMTP using Microsoft Exchange Server, an administrator must create a receive account for BizTalk Server. Once the account is set up, trading partners send their public keys to Exchange Server, which authenticates the sender (trading partner). The public key is added to the Exchange Server certificate store.

When Exchange Server receives a message, the Submit method sends the data to BizTalk Server. BizTalk Server verifies the certificate against the public key; if they match, BizTalk Server decrypts the data and processes the document.

Related Topics

Messaging Port Elements

Select a transport type

Select an encryption certificate

Set Transport Properties


Message Queuing 2.0

Message Queuing 2.0 supports privacy and security using the following:

  • Access control

  • Auditing

  • Encryption

  • Authentication

Message Queuing also takes advantage of the Kerberos V5 security protocol available with Microsoft Windows 2000. In addition, Message Queuing supports 128-bit encryption as well as 40-bit encryption. Message Queuing can also be used to integrate applications, implement a push-style business-event delivery environment between applications, and build reliable applications that work over unreliable but cost-effective networks.

Message Queuing can be used to securely exchange data within an organization and with a trading partner. BizTalk Server 2002 uses Message Queuing to send and receive data using the following methods:

Send

The first layer of security for Message Queuing is a user name and password, which is required by anyone to store data or retrieve data from Message Queuing. In addition, Message Queuing can store data that has a certificate. Users are able to specify a certificate for data stored on a message queue using BizTalk Messaging Manager.

Receive

If an administrator creates logon properties for a message queue, a user name and password must be used to retrieve the data. Creating logon properties forms a fundamental layer of security. If a trading partner has added a certificate to the data, a copy of its private key must be received to decrypt the data before BizTalk Server can process the package.

Related Topics

Add a Message Queuing receive function

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure a Message Queuing receive function: General tab

Configure a Message Queuing receive function: Services tab

Select a transport type

Set Transport Properties


File

Microsoft Windows 2000 ensures data and system protection by defining discretionary file access control. The Windows NTFS file system, required for BizTalk Server 2002, can prevent users from damaging key system or application files. NTFS also provides robust security for the supporting files in an application.

File storage can be used to securely exchange data within an organization and with a trading partner. File storage can also be used to send and receive data using the following:

Send

The first layer of security for file storage is a user name and password. A user name and password is required by anyone storing or retrieving data from a folder. In addition, folders can store data that has a certificate associated with it. To use this added layer of security, use BizTalk Messaging Manager to create a certificate for the data to be stored in a folder.

Receive

If logon properties for a folder have been applied, a user name and password must be used to retrieve the data. An administrator can also designate access levels (read, delete, and so on) to the file directory for specific users. If a trading partner has added a certificate to the data, a copy of its private key must be received to decrypt the data before BizTalk Server can process the package. Inbound documents can also be digitally signed to ensure that the sending source cannot deny that it sent the document.

Related Topics

Add a File receive function

Configure advanced properties for File or Message Queuing receive functions

Configure a File receive function: General tab

Configure a File receive function: Services tab

Select a transport type

Set Transport Properties


Certificates Overview

Digital certificates bind a cryptographic key with one or more attributes of a user. Issued by certification authorities, the certificates protect the Internet by assuring the authenticity of network messages. This technology and its underlying digital signatures are now helping to increase the widespread deployment of electronic commerce on the Internet.

The following topics and procedures are covered in this section:

  • Understanding Certificates

  • Certificates Needed by BizTalk Server

  • Certificate Name Restrictions


Understanding Certificates

Microsoft BizTalk Server 2002 relies heavily on the security provided by certificates. Through the use of public keys, which encrypt the data, and private keys, which enable the data to be decrypted, BizTalk Server can send data that can be trusted and can ensure that the data it processes is secure. Public Key Policies, which are part of the Microsoft Management Console (MMC), enable a user to configure encrypted data recovery agents for Encrypting File System (EFS), domain-wide root certificate authorities, trusted certificate authorities, and so on. Certificates also contain digital signatures, which can be applied to documents and verified on inbound documents using the BizTalk Server native support for digital signatures.

Certificates are used to authenticate and secure exchanges of information on non-secured networks, such as the Internet. Certificates can be managed for a user, a computer, or a service. The X.509-based Public Key Certificate Server built into Windows 2000 Server lets organizations issue public-key certificates for authentication to their users, without depending on commercial Certification Authority (CA) services.

BizTalk Server supports certificates through BizTalk Messaging Manager. Certificates make it easy to encrypt, decrypt, and digitally sign data. Public-key encryption technology is supported for all documents that are transmitted using BizTalk Server transport services. BizTalk Server also supports decryption and signature verification for the documents that it receives.

Note

  • While processing S/MIME messages, the BizTalk Server engine checks to ensure that a certificate has not expired. However, at run time, BizTalk Server does not check if a certificate has been revoked or whether a certificate has a valid and trusted root certificate.

MachineKeys versus UserKeys

When obtaining certificates, it is best to use MachineKeys, which are associated with the computer, rather than UserKeys, which are associated with the current, logged on user. If a user who is currently logged onto a server obtains a certificate with UserKeys, only that user can access the certificate because the certificate UserKey contains that user's logon information. Therefore, if users need to access certificates with UserKeys in BizTalk Server, BizTalk Server must be run in the context of that user. To enable any user to log on to BizTalk Server and access keys, certificates must have MachineKeys.

For BizTalk Server to access the Certificates (Local Computer), either BizTalk Server must run as LocalSystem or Administrator or the security settings of the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates must be modified. Additionally, if UserKeys are used, BizTalk Server must run in the context of that user, who also must be an administrator or be granted permissions to the registry key mentioned previously.

If you do not want to use an Administrator account to run BizTalk Server but still need to use certificates, give the account that the BizTalk Messaging Service is running under full control permissions for the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates.

The following procedure is covered in this section:

  • Configure registry permissions for Certificates


Configure registry permissions for Certificates

To modify the registry permissions for Certificates in Windows 2000:

  1. Click Start, click Run, and then type regedt32.exe.

  2. Click OK.

  3. Locate the following registry key:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates

  4. On the Security menu, click Permissions, and give the account in question full control permissions to this registry key.

Warning

  • Before you edit the registry, make sure you understand how to restore it if a problem occurs. For more information, see "Change Keys and Values" and "Add and Delete Information in the Registry" in Windows 2000 Help. Note that you should back up the registry before you edit it. If you are running Windows 2000, you should also update your Emergency Repair Disk (ERD).

  • Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.


Certificates Needed by BizTalk Server

A certificate server stores certificates for a user and for a computer. Every user has a certificate store, and every computer has its own certificate stores. If a user creates a certificate, Windows 2000 assumes the certificate is for the user. An organization needs to store its certificates in the Personal store located under the Certificates (Local Computer) of the Certificates console. However, during design time, when messaging ports and channels are created, a user needs to have all trading partner certificates associated with the BizTalk store under Certificate (Local Computer) of the Certificates console, rather than with the user.

In addition, when specifying security, such as encryption or signature verification, for trading partners through BizTalk Messaging Manager, the certificates displayed are the trading partner certificates located in the BizTalk store. BizTalk Messaging Manager displays the certificates located in the Personal store under Certificate (Local Computer) of the Certificates console when specifying security, such as verified decryption and signing, for SSL clients. Where certificates are located is important because at run time, when a user attempts to process documents through BizTalk Server, the computer is acting as the background service, and it is this service that needs to access the certificates.

There are two ways to resolve issues about where certificates are stored:

  • If a user has already created certificates, Windows 2000 has stored them in the user store. The certificates must be moved from the user store to the corresponding store under Certificates (Local Computer). This process is done through the Certificate Manager.

  • If a user has created a service account, all the certificates are associated with the computer, rather than with the user.

Certificate management through Windows 2000

BizTalk Server provides certificate management through Microsoft Windows 2000. Tightly integrated within the Windows 2000 security model is IIS 5.0, which includes a certificate server. This lets organizations issue and manage Internet-standard X.509 digital certificates. In addition to key management services in IIS 5.0, the Microsoft certificate server in IIS 5.0 provides customizable services for issuing and managing digital certificates. A certificate server performs a central role in the management of software security systems to enable secure communications across the Internet, corporate intranets, and other non-secure networks.

The following procedure is covered in this section:

  • Create a Certificate Manager for BizTalk Server

Related Topics

Select a certificate for outbound signature

Select a certificate to verify inbound document decryption

Select a certificate to verify inbound document signature

Select an encryption certificate


Create a Certificate Manager for BizTalk Server

BizTalk Server requires that all trading partner certificates be associated with the BizTalk store under Certificate (Local Computer) of the Certificates console, rather than with the user.

  1. On the Start menu, click Run, type mmc, and then click OK.

    The Console1 dialog box appears.

  2. On the Console menu, click Add/Remove Snap-in.

    The Add/Remove Snap-in dialog box appears.

  3. Click Add.

    The Add Standalone Snap-in dialog box appears.

  4. Click Certificates and click Add.

    The Certificates snap-in dialog box appears.

  5. Click Computer account, click Next and click Finish.

  6. In the Add Standalone Snap-in dialog box, click Certificates and click Add.

    The Certificates snap-in dialog box appears.

  7. Select My User account, click Next, click Finish, click Close, and then click OK to close the dialog boxes.

  8. On the Console menu, click Save.

    The Save dialog box appears.

  9. Select the location where you want to save the Certificate Manager (the default is in the Administrative Tools folder), type the name you want for the Certificate Manager, and then click Save.

Notes

  • This task must be performed by a member of the BizTalk Server Administrators group.

  • If you already have a Certificate Manager for your user account, open the Certificate Manager and follow steps 2 through 6 to create a Computer account.

  • Once certificates are created, they need to be moved from the User store to add the Certificate snap-in for the Computer account.

Related Topic

Certificates Overview


Certificate Name Restrictions

You cannot use identical names for certificates in Microsoft BizTalk Server 2002. If identical names for certificates exist, only one of the certificates can be selected in BizTalk Messaging Manager. For example, if an organization uses two certificates that have the same name and reference, it is impossible for the organization to use both certificates. If the organization uses one of the certificates, the other certificate disappears from the list of available certificates in the Channel dialog box.


CryptoAPI

Microsoft BizTalk Server 2002 uses CryptoAPI to secure data it processes. Recent developments in cryptography have added additional uses, including mechanisms for authenticating users on a network, ensuring the integrity of transmitted information, and preventing users from denying ownership of their transmitted messages.

Any application, message, data, and so on that uses encryption and uses Microsoft-specific encryption, such as Microsoft Windows 2000 for generating certificates, uses CryptoAPI. BizTalk Server uses CryptoAPI for receive functions that a user specifies when using a custom-made COM+ component such as a preprocessing component, which enables BizTalk Server to handle unique encryption components.


Collaboration Data Objects

Microsoft BizTalk Server 2002 supports MIME encoding for both sending and receiving data. Through the use of Collaboration Data Objects (CDO), a technology that is part of the Microsoft Windows 2000 environment, data can be encoded and processed by BizTalk Server. For example, before BizTalk Server can send a catalog that contains text and graphics, it first needs the data (graphics) to be changed from binary to string. CDO can be used to encode the text and graphics into a string format so that BizTalk Server can process it.


Configuring Firewalls

Firewalls help secure internal networks, but they also introduce latency and have the potential to create a single point of failure. Even if a load-balancing mechanism is used to alleviate the single point of failure, a firewall can reduce a network's performance.

When configuring a BizTalk Server 2002 environment with a firewall, two primary configurations are recommended:

  • Configuration 1. Install servers on an internal corporate network. Select some of these servers to communicate to trading partners on a corporate perimeter network (also known as DMZ or demilitarized zone). A company that wants to host its own Internet services without sacrificing unauthorized access to its private network uses a perimeter network. The perimeter network is the boundary between the Internet and an internal network's line of defense, usually a combination of firewalls and bastion hosts, which are gateways between internal networks and external networks. The servers in the perimeter network should use local transport services, such as HTTP, Message Queuing, or SMTP. In this environment, all inbound and/or outbound transactions will pass through a firewall. The servers in the perimeter network send documents through another firewall to Microsoft SQL Server. This configuration will allow servers, such as BizTalk Server in the perimeter network, to communicate with Microsoft SQL Server through an internal firewall.

  • Configuration 2. Install the servers on a corporate network. Trading partners exchanging documents through the Internet send their data using SMTP servers in the perimeter network (first firewall of protection). These servers then send the data to the servers residing on the corporate network through a second firewall.

Configurations 1 and 2 will impact performance. To avoid a noticeable degradation in performance, you can construct the firewall to accommodate a typical number of transactions between an organization and its trading partners.


Enhancing Performance and Scalability

Understanding the various components of Microsoft® BizTalk™ Server 2002 enables you to create scalable, high-performance solutions. There are several methods, such as identifying potential bottlenecks, addressing latency, and managing databases, which you can use to increase the performance of BizTalk Server. However, the extent to which you can achieve an optimal solution depends on the complexity of your organization's system architecture and your budget requirements.

Optimizing the following BizTalk Server databases is critical to achieving high performance:

  • BizTalk Messaging Management database

  • Shared Queue database

  • Tracking database

  • Orchestration Persistence database

For more information about optimizing the databases, see Scale Up the Databases and Scale Out the Databases.

The following topics are covered in this section:

  • Performance Optimization

  • Scaling BizTalk Server


Performance Optimization

To meet your transaction requirements and enhance performance, you must optimize BizTalk Server 2002. In addition to BizTalk Server, you can optimize Microsoft® Windows® 2000 and database interactions to enhance performance.

After configuring your system, test it, and then evaluate the results to determine if your initial configuration can meet your transaction requirements. It is likely that you will need to reconfigure your architecture to achieve optimal performance. After each reconfiguration, test it again and evaluate the results. Once you have achieved the results you want, initiate a maintenance plan, because server performance changes over time, and the quantity and type of transactions that your organization handles might change.

The following topics are covered in this section:

  • Tuning the Performance of Your BizTalk Server Architecture

  • Architecture Design, Testing, and Analysis

  • Maintaining Performance


Tuning the Performance of Your BizTalk Server Architecture

This section provides general recommendations for optimizing system settings, and includes topics for optimizing BizTalk Server 2002 to obtain increased performance.

When tuning the performance and scalability of BizTalk Server it is important to first understand all of the characteristics of your system. With few exceptions, the bottleneck will be in one of the following areas:

  • Disk I/O

  • Processor speed

  • Network I/O

  • Input speed (how fast your documents are sent to BizTalk Server)

  • Custom code (for example, AICs, preprocessor components, or ASP pages to which you are posting)

The topics in this section provide help on how to address these problems. First, you must analyze the performance of your current configuration to determine where your problem is. Even if you are satisfied with the current performance of your system, analyzing and understanding the properties of your system is important and will save you time when troubleshooting or upgrading.

The first five steps recommended to analyze the performance of a system are:

  1. Monitor the disk I/O on all the computers in the BizTalk Server configuration by checking the performance counter %disk idle time through the Windows System Monitor or Microsoft Operations Manager (MOM). Monitor this performance counter for all BizTalk Servers, SQL Servers, and any additional computers that interact with BizTalk Server, for example, through application integration components (AICs) or HTTP post. For more information, see Evaluating the Performance of a Configuration.

  2. Monitor the processor utilization on all the computers in the BizTalk Server configuration by checking the performance counter %processor utilization through the Windows System Monitor tool or MOM. If you find that the processor is overloaded on a BizTalk Server, you can optimize performance by modifying server, channel, and registry settings. For more information, see Add, Delete, and Configure Servers in a Group, Add, Delete, and Configure a Server Group, Optimizing Registry Settings, and Scale out BizTalk Messaging Services. In an optimally configured BizTalk Server system, the processor utilization will be the only point where bottlenecks occur.

  3. Do not allow any of the servers to participate in work-item processing and rerun your scenario so that items build up in the Work queue. This will give a good indicator of how fast documents are received. Spend time analyzing the first two steps again, as well as looking at other potential issues. One common issue is slow input rate occurring when using ASP submit calls. Often Internet Information Services (IIS) cannot handle the requests fast enough to drive BizTalk Server to a peak performance. When using an ASP submit call, it is recommended to switch to the BizTalk Server ISAPI-based HTTP receive functions, as they will perform a lot better. In an optimally configured BizTalk Server system, processor utilization is the bottleneck for receiving documents.

  4. Shutdown the receive functions or stop calling the Submit method and allow the servers to participate in work-item processing with items already in the Work queue. This will give you a good indication of how fast you can process and transmit documents. Again, analyze the first two steps and tune the system until processor utilization is your bottleneck. To determine whether the transport is the reason for the slowed performance, it is recommended to change the transport type of the ports. When using AICs, this is a good indicator as to how much work you still need to do to achieve maximum performance from your AICs.

  5. Balance the input and output of the system. After you have eliminated all your resource bottlenecks and have the CPU utilization of your servers above 90 percent, it is important to balance your receive rate and processing rate so that you have between 40 and 100 documents in your Work queue at any given time. For more information, see Balancing Receiving and Processing.

The following topics are covered in this section:

  • Balancing Receiving and Processing

  • Optimizing BizTalk Orchestration Services

  • Optimizing BizTalk Messaging Services

Related Topic

Scaling BizTalk Server


Balancing Receiving and Processing

After you have eliminated all your resource bottlenecks and have the CPU utilization of your servers above 90 percent, it is important to balance your receive rate and processing rate so that you have between 40 and 100 documents in your Work queue at any given time. Follow these guidelines to help you balance the number of documents you receive and the number of documents your system processes:

  • Generally, you cannot process more documents than you receive. If receiving documents is too slow, it will limit the number of documents you can process in a given time. Indications that receiving documents is slow are:
    • Your Work queue will often be empty.

    • When monitoring the performance counter Documents Processed/sec, you notice that document processing frequently drops toward zero.
  • If you optimize your system for receiving documents, you may limit the resources available to process documents, and reduce your throughput. Indications that there are not enough resources for processing documents are:
    • The number of documents in the Work queue continues to rise over time.

    • The System Monitor may show that you are receiving documents faster than you are processing them.

    Important

    • You can rely on the previous symptoms if each document received matches exactly one channel. If your configuration matches a single document to more than one channel, you will need to adjust your comparisons. For example, if your configuration matches each incoming document to exactly two channels, your maximum document throughput will be twice the number of documents you receive.


Optimizing BizTalk Orchestration Services

Using BizTalk Orchestration Services, you can optimize XLANG schedules and the contents contained within schedules. By understanding how schedules use memory and how the structure of a business-process flow affects performance, you can design schedules that improve the performance of BizTalk Orchestration Services. Implementation technologies that are supported by BizTalk Orchestration Services include BizTalk Messaging Services, COM components, Message Queuing Services, and Windows Script Components. By optimizing these components and services, you can further enhance the performance of BizTalk Orchestration Services.

The following topics are covered in this section:

  • Optimizing XLANG Schedules

  • Optimizing the Contents of XLANG Schedules


Optimizing XLANG Schedules

An XLANG schedule can contain a large number of internal business processes. The business processes may include short-lived transactions or long-running transactions. While BizTalk Server does not control the contents of these processes, it does manage the flow of information through these processes within an XLANG schedule. When designing an XLANG schedule, whether it consists of several short-lived transactions or long-running transactions, consider the following:

  • An XLANG schedule instance runs in memory each time it is invoked.

  • Multiple XLANG schedules may run on the same server.

  • Several different XLANG schedules may be running concurrently, with multiple XLANG schedule instances.

The Orchestration Persistence database provides a mechanism, called dehydration, to control the memory that is used by running XLANG schedules. Dehydration occurs if an XLANG schedule instance is waiting for a message, and no other activity is occurring within the XLANG schedule. At this point, the XLANG Scheduler Engine dehydrates the XLANG schedule instance to maximize performance. Dehydrating an XLANG schedule instance consists of persisting all instance-specific states to a database and removing the instance from memory. Only a small portion of the XLANG schedule instance remains in memory within the XLANG Scheduler Engine. When a message arrives at a port for the XLANG schedule instance, the instance is rehydrated. Rehydrating an XLANG schedule instance consists of restoring the instance from the database to memory.

An XLANG schedule instance remains dehydrated until it is either rehydrated or explicitly terminated by an administrator. This enables a business process to run reliably for an extended time period. For more information about configuring hydration settings, see Dehydration and Rehydration. While dehydration and rehydration saves memory, it does affect performance. Because dehydration and rehydration requires that data be read and written to the Orchestration Persistence database, network latency is incurred.

Important

  • To dramatically increase the performance of BizTalk Orchestration Services, in Windows Explorer browse to Program Files\Common Files\System\ado, and then double-click adofre15.reg. In the confirmation dialog box, click Yes, and then click OK. Keep in mind that this procedure changes the ADO threading model from "Apartment threaded" to "Both" and might affect other applications that use Microsoft® ActiveX® Data Objects (ADO).


Optimizing the Contents of XLANG Schedules

An XLANG schedule describes the business process and the binding of that process to implementation technologies. The performance of an XLANG schedule often mirrors the performance level of the actions contained within it. There are a number of relevant issues for optimizing the contents of an XLANG schedule. Some of these are things specific to an XLANG schedule, while others are applicable to authoring any distributed application:

  • Reset the dehydration value to conserve memory for XLANG schedules. The default wait time is 0 seconds. You can change this time. Any time less than or equal to 180 seconds causes the XLANG schedule to never dehydrate. Any time greater than 180 seconds causes the XLANG schedule to dehydrate immediately. For more information about wait times and XLANG schedule dehydration, see Dehydration and Rehydration and Synchronous and Asynchronous Communication.

  • Use persistent components. Persistent components, such as components that implement IPersistStream or IPersistStreamInit, enable the XLANG Scheduler Engine to dehydrate XLANG schedules flexibly.

  • Run the COM objects on the same server as the Orchestration Persistence database. This ensures that the XLANG schedule does not incur the network latency.

  • Run COM+ packages in-process to achieve optimal performance. Although running a COM+ package in-process can affect the stability of the COM+ application (for example, if one component within the application fails, the entire application can fail), it is significantly faster than running the application out-of-process. To avoid this potential instability, be sure to heavily test the components within the application for stability prior to deploying the application to a production environment.

  • Batch work into a single transaction. Persisting the state of an XLANG schedule instance at the beginning and end of a transaction greatly impacts the computer's resources. However, batching work items in a single transaction greatly reduces this impact to performance. In addition, an XLANG schedule cannot dehydrate in the middle of a Microsoft Distributed Transaction Coordinator (MS DTC) transaction. MS DTC transactions are quick, but they degrade performance. Group multiple actions within a single MS DTC transaction, provided the actions can be completed quickly.

  • Long-running transactions should be accomplished asynchronously and XLANG schedules should be designed to complete COM calls quickly. Results from asynchronous work can be communicated back to the XLANG schedule instance through message queues, or through COM calls. With COM, the name of a "response" port can be passed in the form of a moniker that will be valid even with computer restarts.

Related Topic

Moniker Syntax


Optimizing BizTalk Messaging Services

To optimize BizTalk Messaging Services send documents to a server group. BizTalk Server groups are used to distribute work across multiple servers. To send data to BizTalk Server, use the following methods:

  • Configure a receive function (such as Message Queuing, HTTP or File).

  • Call the Submit method on the BizTalk Server Interchange object.

Using receive functions provides better performance than using the Submit method to call the Interchange object. Receive functions use a thread pool and batching to optimize receive performance. To achieve similar performance in client code that invokes IInterchange::Submit(), the client component must implement Multithreaded Apartment code where each thread owns a separate pointer to IInterchange. If Single Threaded Apartment code is used, it serially submits messages into BizTalk Server and does not achieve the throughput performance of using receive functions and Message Queuing.

Calling the Interchange object for submission rather than using a receive function uses more resources because the Interchange object needs to be created outside the BizTalk Server process. However, if the Interchange object is used, there are two methods available for sending data to the servers in a group:

  • Statically configure portions of the total submissions to specific servers within the group. However, this does not provide much fault tolerance if the server, which has a transport service, is statically mapped to a BizTalk Server that has failed.

  • Use the Microsoft Application Center 2000 Component Load Balancing (CLB) functionality to improve performance. BizTalk Server groups do not provide load balancing for the submission of documents. In addition to load balancing, CLB provides fault tolerance. For more information about CLB, see Component Load Balancing.

The following topics are covered in this section:

  • Creating and Optimizing Specifications

  • Creating and Optimizing Maps

  • Optimizing BizTalk Server Group Properties

  • Optimizing Server Properties

  • Optimizing Registry Settings

  • Optimizing Encryption

  • Optimizing Communication

  • Configuring Firewalls


Creating and Optimizing Specifications

If the default global tracking settings are used, BizTalk Server 2002 can support a 20-MB XML Unicode format document. For other file types, such as an ANSI flat file, BizTalk Server does not support a 20-MB file size because any file that is not XML has to be converted to XML. The conversion process adds XML tags to the data, thus increasing the size of the document that BizTalk Server needs to process. Other file types must be less than 20 MB to maintain optimal performance by BizTalk Server.

The amount of memory required to process a document that has been converted to XML depends on the original structure of the document. If global tracking settings are enabled, XML Unicode format documents that are larger than 20 MB can be processed without greatly impacting BizTalk Server performance.

Note

  • Exceeding the size limit for tracking interchanges will impact the performance of BizTalk Server. For more information about the size limit, see Interchange and document size limit. Performance is also affected by document logging. For more information about document logging, see Set document logging properties.

When designing specifications, you can configure validation rules within a specification. For example, you can specify that a field contain a particular data type (such as a string) or more complex rules (such as requiring a field to be validated against a list of 80 values). The latter requires that the data be checked against 80 values and, if it does not conform to one of them, the specification fails validation. Specification validation in BizTalk Server is enabled by default; it affects performance but ensures the validity of the data being sent or received. You can disable validation, which increases performance and might not adversely affect the validity of data because BizTalk Server has several other mechanisms for validating data.

For example, if you have a map that requires certain data types and values and specification validation is disabled, the data successfully passes the parsing phase but fails during the serializing phase when the map is applied. If other mechanisms (such as maps that rely on valid data) are available, specification validation can be disabled to avoid the potential performance degradation caused by the validation process. Alternatively, you might choose to do so because you have agreed to data standards with business partners and have validated these transactions. You might also choose to do so because you have complete control of how the data is sent (such as application-to-application transactions).

You can use the NoValidation registry setting to disable validation. If specification validation is not required (documents are not validated against a specification for settings such as minimum/maximum values, data types, and/or required values), set this to a non-zero value and the data will not be validated. This might help with performance, but may result in non-valid data being sent. Changing the specification validation to a non-zero value might be the right option for servers that are receiving documents for which the organization has control over the structure.

The registry setting is accomplished at the individual server level. When specification validation is on, every document processed by the server is validated against its specification. This performs more slowly than if no specification validation were used.

Recommended solutions for optimizing document size and specifications

To optimize performance of BizTalk Server:

  • Do not include more fields and/or attributes in specifications than necessary. Increased fields and attributes equate to increased memory requirements for BizTalk Server. A larger specification requires a proportional increase in memory. For example, the EDI specifications included with BizTalk Server are compliant with EDI standards. Typically, most organizations that use EDI specifications require approximately 10 percent of the entire specification. So, if an organization and its trading partner use only 10 percent of the entire specification, the unnecessary records and fields can be deleted and the modified specification can be used for transactions.

  • If specification validation is enabled, do not specify validation rules in specifications for fields that will contain valid data. For example, if a field contains a number but will be processed only as a string (a phone number, for example), do not specify that it must be numeric. In this situation it is not necessary to specify a data type because the default data type is string. Therefore the data type field could be left blank. Specifying acceptable values for a field takes longer to validate than a simple data type validation.


Creating and Optimizing Maps

Translating data, as part of a transaction, might reduce the performance of BizTalk Server 2002. Mapping specifications can be CPU-intensive, which can reduce the ability of BizTalk Server to process the overall transaction. The level to which BizTalk Server is affected depends largely on the complexity of the map being used for translation. For example, mapping a field called productID in the source specification to a field called itemID in the destination specification is not as intensive as performing a complex mathematical operation on the data being translated.

Recommended solutions for designing maps

  • Use functoids only when needed. Functoids use script, which causes BizTalk Server to load a scripting engine. This might degrade performance as compared to native XML transformations.

  • Use the Database Lookup functoid only when needed. BizTalk Server must establish a database connection, query for data, populate a recordset, and close the connection each time this functoid is used. This might degrade performance of BizTalk Server.

  • Avoid invoking COM objects within functoid scripts and using custom functoids. Both of these techniques cause BizTalk Server to instantiate an instance of a COM object. This affects the performance of the overall operation. In addition, the performance of instantiating COM objects is affected by the answers to the following questions:
    • Is it in-process or out-of-process?

    • Is the object local or remote?

    • How well is the object written?

    • Is it transactional?
  • Analyze each map to determine how to achieve optimal performance. For example, two different techniques can be used to concatenate two source fields together and have the resultant value placed in two different destination fields. The first concatenation technique would be to use one concatenation functoid and map its output to two places. The second concatenation technique would be to use two functoids each with a single output link to a destination source field. The first technique is slightly more efficient due to the fact that the script, which runs as part of the functoid, is called only once. Through testing, you can determine which techniques result in the best performance.


Optimizing BizTalk Server Group Properties

In BizTalk Server Administration, you can specify the following properties in the BizTalk Server Group Properties dialog box:

  • Messaging Management object cache refresh interval (seconds). This field can be set to a maximum of 300 seconds. BizTalk Server 2002 caches configurations (such as channels, messaging ports, envelopes, and document definitions) in memory to avoid calling the database each time. If these objects are not regularly changed, set this value to 300 to reduce the number of times data is written to and read from the database. Because BizTalk Server refreshes management objects every five minutes, the service must be restarted for the change to take effect immediately.

  • 1Disable document tracking. The Tracking tab can be used to enable or disable document tracking. If tracking is not used, disable this field to minimize the number of read/writes to the database for a single transaction. If this field is enabled, BizTalk Server connects to the database and logs data. Do not disable this field unless tracking is not needed. However, it is highly recommended that document tracking remain enabled. For more information about setting tracking properties, see Configure tracking properties for a server group.

    Note

    • A size limit exists for tracking interchanges. If the size limit is exceeded, the performance of BizTalk Server will be affected. For more information about the size limit, see Interchange and document size limit. Performance is also affected by document logging. For more information about document logging, see Set document logging properties.
  • Arrange the server call sequence. BizTalk Server parsers can be prioritized if a group is predominately receiving a particular document type. BizTalk Server has four parsers that it uses to parse data: XML, EDIFACT, X12, and Flat File. When BizTalk Server receives a document, it tries to parse it using these parsers in the order in which they are listed. If an organization primarily receives a particular document type, the order of the parsers should be changed so that the first one matches the type of documents being received.

Related Topic

Scale Out BizTalk Messaging Services


Optimizing Server Properties

In BizTalk Server Administration, you can set the following properties in the <Server> Properties dialog box:

  • Create multiple instances of receive functions. This will enable BizTalk Server to poll multiple receive functions for documents to retrieve. To balance the load of documents across several computers, locate the receive functions on separate computers. Each polling location must be unique and must have a separate receive function. To avoid overloading any individual receive function, the business application that sends documents must evenly distribute the documents to all the polling locations.

  • Maximum number of receive function threads allowed. You can specify how many receive function worker threads per processor you want for a receive function. Setting this too low can cause a slowdown in BizTalk Server because it uses I/O completion ports. Setting this too high should not have serious effects, but it might cause performance degradation. You can adjust this number to find the optimal value for their setup. The recommended value for the Maximum number of receive function threads allowed is 4.

  • Maximum number of worker threads per processor allowed. You can specify the number of worker threads per processor for the processing side. By appropriately adjusting the number of worker threads, you can improve performance. In BizTalk Server Administration, right-click a server in the console tree and click Properties. Change the default value in the Maximum number of worker threads per processor allowed box. The default value is 4. The recommended value is from 10 to 16, depending on the deployment.


Optimizing Registry Settings

To improve the performance of BizTalk Server, you can implement the following registry setting adjustments.

Warning

  • Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.

  • For more information, see "Change Keys and Values" and "Add and Delete Information in the Registry" in Windows 2000 Help. Note that you should back up the registry before you edit it. If you are running Windows 2000, you should also update your Emergency Repair Disk (ERD).

All of the following keys should be added as DWORD values to \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BTSSVC:

  • NoValidation. Use this registry key to disable specification validation. If specification validation is not required (documents are not validated against a specification for minimum/maximum values, data types, or required values, for example), set this to a non-zero value and the data will not be validated. While this might improve performance, it may result in non-valid data being sent. This setting would be appropriate for servers that are receiving documents for which the organization controls the structure.

  • ParserRefreshInterval. By default this is set to 60,000 (60 seconds). This value indicates how often BizTalk Server should check the database to see if a new parser has been added (this is the only group-level property that is refreshed while the server is running). If no new parsers will be added, set this value to 0 and BizTalk Server will not check the database. This value is also used to verify if the group settings in the Tracking database have been modified, and whether the parser list has been modified by adding, deleting, or rearranging parsers.

  • CacheSize. Use this registry key to indicate how large the BizTalk Server management object cache is allowed to grow. The default value for this is 20. Therefore, as soon as the BizTalk Server object cache exceeds 20 channels, messaging ports, envelopes, or document definitions, BizTalk Server must delete some items from memory. If a server has a high volume of memory, this value can be set higher (above 20) and BizTalk Server will keep more in memory. This does not affect the refresh interval. BizTalk Server deletes the cached objects and reloads them when they have expired.

  • BatchSize. Use this value only with a Message Queuing receive function. By default BatchSize is set to 20. To improve performance, BizTalk Server reads up to 20 items at a time from the queue and sends all 20 within one transaction. Reducing the number of times data is written to a database will greatly improve performance. If a deadlock occurs and BizTalk Server ends the transaction, it must resubmit the items. BizTalk Server does not lose the documents. Values that exceed 20 have not been tested. Do not set this value to 0.

You can also optimize the registry settings to improve BizTalk Server HTTP receive function performance. All keys should be added as DWORD values to \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BTSSVC\HTTPListener. To improve performance, you can implement the following registry setting adjustments:

  • WorkerThreads. Use this value to modify the number of threads servicing the thread pool. By default WorkerThreads is set to 6. If the document throughput for the HTTP receive function is very high, you might need to increase the value of WorkerThreads and the following QueueFactor setting. An indication that the WorkerThreads key needs to be increased is when the following error message appears in the Event Log:

    The BizTalk HTTP receive function <name> could not retrieve a thread from the thread pool.

  • QueueFactor. Factor by which the number of threads in the pool is multiplied to determine the Queue size. In other words, QueueFactor affects the size of the queue used by the thread pool. The default value for QueueFactor is 3. If the document throughput for the HTTP receive function is very high, you might need to increase the values of WorkerThreads and QueueFactor. An indication that the QueueFactor parameter needs to be increased is when following error message appears in the Event Log:

    The BizTalk HTTP receive function <name> could not post the work item to the thread pool. Try increasing the length of the thread pool queue using the registry key "QueueFactor".

  • AsyncBufferSize. This is the size of the buffer for doing IIS asynchronous reads, and the recommended buffer size for object-oriented programming (OOP). The default value for AsyncBufferSize is set to 4,096 bytes. When data is received that is greater than 48 kilobytes (KB), the portion of data greater than 48 KB is read asynchronously from IIS.

  • MaxSyncFileDropSize. This is the maximum size of data that will be dropped to a file synchronously; that is, this value is the threshold over which the data is written to file in small pieces. Data received that is smaller than this value is read into memory and then written to file in a single attempt. Data that is bigger than this will be dropped asynchronously and thus the data will not be loaded into memory. By default MaxSyncFileDropSize is set to 1,048,576 bytes. To increase the performance of the receive function, you can decrease the value of MaxSyncFileDropSize. If system resources are limited, you might want to reduce this value to limit memory usage by the HTTP receive function.

  • MaxLargeAsyncBuffers. Use this value to modify the number of allocated buffers for large data. These buffers are cached when the data is larger than 48 KB and less than MaxSyncFileDropSize for file drop. These buffers are used when either the data is submitted directly to BizTalk Server (asynchronously or synchronously) or the data is dropped to a file and the data size is less than MaxSyncFileDropSize. By default the value of MaxLargeAsyncBuffers is 18. You can reduce this value to limit the amount of memory usage of the HTTP receive function, but this will have a detrimental affect on performance.

  • ConfigRefreshInt. This value determines the time interval, in milliseconds, for getting configuration data from the BizTalk Messaging Management database. By default the value of ConfigRefreshInt is set to 60,000 milliseconds. Increasing or decreasing the value of ConfigRefreshInt will depend on how much the BizTalk Messaging Management database is updated.


Optimizing Encryption

Using encryption or other security mechanisms might decrease the performance of BizTalk Server. When using encryption, the following is recommended:

  • Increase the number of servers. Enables you to improve performance by separating and optimizing the different BizTalk Server components.

  • Use a faster CPU. Increases the processing speed.

  • Separate BizTalk Server functionality. For example, send and receive functions can be placed on separate servers.

  • Use an existing virtual private network (VPN) if File, Message Queuing or HTTP is used. If a VPN is available, data transfer is secure. It is not required to secure BizTalk Server transactions if all data transfer conducted with trading partners is secured through a VPN.

  • Purchase encryption hardware accelerator cards. Accelerator cards provide dedicated processors that might eliminate the performance impact of encryption and decryption on the CPU of a server. Accelerator cards are less expensive than adding multiple CPUs.


Optimizing Communication

BizTalk Server provides both synchronous communication and asynchronous communication integration mechanisms. BizTalk Server 2002 can accept documents through COM integration or through server receive functions (File, Message Queuing, or HTTP).

Typically, when a document is sent to BizTalk Server, it is placed in the Shared Queue database. BizTalk Server polls the database and then processes the document. This process is an asynchronous communication mechanism. It uses the checkpoint information in the Microsoft SQL Server database as a queue for retrieving documents that are waiting to be processed. This extra layer of abstraction allows the transport service to send documents to BizTalk Server independent of the transport mechanism used to deliver the documents.

A synchronous communication interchange bypasses all queues, and processes all the components required by the messaging port on the calling thread. For synchronous communication protocols an optional response document is returned, if available. This method is valid only for a single channel match and only for a single messaging port (not for distribution lists).

If the parameters that are set cause multiple channels to match, a synchronous communication submission returns an error which indicates that multiple channel matches are not allowed for a synchronous communication submission. This method can be used only for single document interchanges. If the submission contains multiple documents, an error is returned for synchronous submissions, which indicates that multiple document submissions are not allowed. This method does not support groups.

Synchronous communication is not scalable. Synchronous communication uses a single thread to process a transaction and cannot be load-balanced with other servers in the group because the entire process must run on the server that sends documents.

The synchronous communication mechanism sends documents directly to BizTalk Server for immediate processing. BizTalk Server blocks the return to the caller of the IInterchange::SubmitSync method until processing is completed, whereby a response document is delivered to the caller. This mechanism is available only to the COM-based integration method.

Recommended solutions for optimizing synchronous and asynchronous communication

To achieve optimal performance and scalability, asynchronous communication is highly recommended. Asynchronous communication is highly scalable and provides a high level of throughput. Synchronous communication calls provide a near-immediate response to the caller under a high volume of transactions because each SubmitSync call runs under a separate thread.

However, if there are many calls at once, this leads to many threads running on a single server thereby degrading the overall performance of BizTalk Server. Microsoft Windows 2000 is designed to context-switch between all the threads, thus degrading the overall performance of BizTalk Server. Additionally, the following criteria cause a synchronous communication submission to fail but do not cause an asynchronous communication submission to fail:

  • The transaction criteria matches more than one channel.

  • The interchange contains multiple documents.


Architecture Design, Testing, and Analysis

The key components of BizTalk Server 2002 include the BizTalk Services, the BizTalk Server databases, and the transport services. Poor configuration of any component can degrade the performance of the entire system.

This section provides information about defining, testing, and refining the architecture of BizTalk Server to optimize performance.

The following topics are covered in this section:

  • Architectural Design

  • Architecture Testing and Analysis

Related Topic

Scaling BizTalk Server


Architectural Design

Prior to implementing BizTalk Server 2002 in a production environment, it is highly recommended that you implement a test environment where you can test the different factors that affect the performance of BizTalk Server so that you can determine the best BizTalk Server architecture configuration for your company based on your expected needs. Performance testing is successful when accomplished with controlled processes. It is important to start with a few variables and then slowly add additional variables. When performance begins to degrade, you can identify the cause of degradation.

When determining the best BizTalk Server architecture for your organization, it is important to keep in mind the following factors that affect the number of documents that can be processed by BizTalk Server:

  • Specification validation

  • Application integration components (AICs)

  • Transport services

  • Encryption

  • BizTalk Orchestration Services

  • Firewalls

  • Maps

You must also consider the size of the documents being processed, as well as the current server configuration.

The following topics are covered in this section:

  • Develop Transaction Components

  • Identify Transports

  • Initial Architecture

Related Topics

Administering Servers and Applications

BizTalk Orchestration Services

Application Integration Components

Creating Specifications and Mapping Data

Using BizTalk Mapper

Run XLANG Schedules

Use BizTalk Orchestration Designer


Develop Transaction Components

To develop transaction components, you must design transactions and set transaction properties for business processes. For more information about designing transactions and setting transaction properties, see:

  • Designing Business Processes

  • Designing Transactions

  • Transaction Properties for an XLANG Schedule Drawing

To develop transaction components, you must first determine the transaction types that the components process. In an application-to-application and/or business-to-business environment, you must determine transaction needs and transaction profiles. For example, you might have a scenario in which a single transaction receives a custom XML purchase order and maps it to a standard EDI purchase order, which is later processed by a custom internal application.

This scenario requires that you create a specification for the XML purchase order and a specification for the EDI purchase order. To create these specifications, use BizTalk Editor, which includes XML and EDI templates. Because the templates include all potential records and fields, you can remove unnecessary records and fields, and then save the templates as the final specifications. During design time, any fields in a specification that require validation decrease the performance of BizTalk Server 2002. For more information about optimizing specifications, see Creating and Optimizing Specifications.

In addition to creating a specification, you must map data. Because there are a number of ways to translate data in map files (by using XSLT translations, functoids, or a custom script), all of which affect performance, it is important to test different translation methods. Testing one method of data translation over another helps to reduce performance impacts to BizTalk Server as a result of mapping. For more information, see Creating and Optimizing Maps.

For information about techniques that can help you to determine the most efficient transaction configuration, see Evaluating the Performance of a Configuration.

Note

  • Some errors returned by Microsoft XML Parser (MSXML) within a custom script function may not be passed to the server. Errors associated with a document in the Suspended queue may not reflect the error returned in the script.

Related Topics

Designing Business Processes

Designing Transactions

Identify Transports

Transaction Properties for an XLANG Schedule Drawing


Identify Transports

To determine how to send and receive data, consider if the following are in use:

  • Business-to-business transactions

  • Application-to-application transactions

  • Transport services (send and receive)

  • Encryption

  • HTTPS or S/MIME

Consider whether different transports are needed based on the type of transactions you are processing. Determine whether unique transports are required for business-to-business and application-to-application transactions or if the same transports can be used for these two types of transactions.


Initial Architecture

To successfully plan an initial architecture, consider the following:

  • One server with Microsoft SQL Server and BizTalk Server can be used to process a low volume of transactions.

  • Installing BizTalk Server and SQL Server on separate servers can provide for a moderate volume of transactions.

  • An existing SMTP transport service can be used to send and receive data. Placing this service on a separate server is recommended for this transport type.

  • HTTP, Message Queuing, or File transport services can be used to write data to disk drives on servers other than the local BizTalk Server, which can improve BizTalk Server performance.

An initial architecture should contain as many separate servers as possible. For example, within a company, one person might administer SMTP servers and Message Queuing, whereas another person might handle security policies. The goal of the initial architecture is to determine how many servers are needed and the hardware required by those servers to process the anticipated work. After you determine the required number of servers, test the initial architecture.

Related Topic

Architecture Testing and Analysis


Architecture Testing and Analysis

Prior to testing the architecture, you need to:

  • Define the architectural components.

  • Determine the transaction needs and profiles.

  • Determine what transaction components need to be developed.

  • Determine the necessary transport services.

You begin this process by creating a baseline, which will require the following:

  • Configure the BizTalk Messaging Services, organizations, document definitions, channels, and messaging ports needed to process transactions.

  • Configure BizTalk Orchestration Services.

  • Install and/or configure any COM+ applications, BizTalk Server channels, databases, or message queues required for XLANG schedules.

Once a baseline has been established, process transactions using BizTalk Server. This helps to identify factors affecting performance.

The following topics are covered in this section:

  • Evaluating the Performance of a Configuration

  • Improving the Architecture

Related Topics

Architectural Design

Scaling BizTalk Server


Evaluating the Performance of a Configuration

You can use the Microsoft Windows 2000 Performance tool to test the performance of BizTalk Messaging Services.

To use the Performance tool, on the Start menu, point to Programs, point to Administrative Tools, and then click Performance. The System Monitor, which is part of the Performance tool, graphically displays counter readings as they change over time. There are, however, different counters that should be monitored depending on the system component being monitored. Numerous white papers are available describing how to monitor performance for Windows 2000, Internet Information Services (IIS), SQL Server, and Message Queuing; however, the following tables lists only some of the primary objects and counters to monitor. In addition, the table contains specific information regarding the objects and counters to monitor to determine BizTalk Messaging Services performance.

Object | Counter | Observation | Component affected
Active Server Pages | Requests queued | There should not be a significant queue except at peak periods. | HTTP transport services that use .asp pages
 | Requests/sec | Indicates the volume of ASP requests the HTTP transport services are receiving (if using ASP). If files are posted to an HTTP page, this counter does not provide any pertinent information. | HTTP transport services that use .asp pages
 | Request wait time | Close to zero. | HTTP transport services that use .asp pages
Network Segment | Bytes received per second/Bytes sent per second | If this number is close to the capacity of the connection, and processor and memory use are moderate, the connection might affect performance. | All
Process, Inetinfo instance | Private bytes | Monitor this for memory leaks or size approaching maximum available RAM. | HTTP transport service
Memory | Available bytes | Available bytes should not stay below 10 MB consistently. If so, a memory spike would cause paging to disk to start. | All
 | Page Faults/sec, Memory: Pages Input/sec, and Memory: Page Reads/sec | If these numbers are low, the server should be responding to requests quickly. If they are high, an increase in the amount of RAM on your server might be needed. | All
Physical Disk | Disk read/sec and Disk writes/sec | Combined, these two counters should be significantly under the maximum capacity for the disk device. To enable this counter, on the Start menu, point to Programs, point to Accessories, and then click Command Prompt. At the command prompt, type diskperf –y. Then, restart the computer. | SQL Server, Message Queuing, and File transport services
 | % Disk time | This counter should be well below 100 percent. If it is above this value (and it can go into the 1,000 percent range), add more physical disks or move one of the databases to another server. The value of this counter is dependent on your RAID configuration. | SQL Server, Message Queuing, and File transport services
 | % Idle time | This counter should be above 20 percent. If it is below this value, add more physical disks or move one of the databases to another server. The counter % Disk Idle time is a better indicator than % Disk utilization, because it is independent of your RAID configuration. If one of your disks is being overloaded, you will need to repartition the load across other physical disks or add more disks to the stressed drive. | SQL Server, Message Queuing, and File transport services
 | Current Disk Queue Length | This counter is the number of requests outstanding on the disk at the time the performance data is collected. This counter should average less than 2 for good performance. | BizTalk Server, SQL Server
SQL Server | I/O transactions/sec | Indicates how much activity the SQL Server actually performs. | SQL Server
BizTalk Server | Documents Processed/sec | Indicates how quickly BizTalk Server 2002 is polling documents from its Work queue and sending them. | BizTalk Messaging Services
 | Documents Received/sec | Indicates how quickly BizTalk Server is sending documents to the Work queue. This number reflects only the number of documents BizTalk Server has received (this includes documents that fail parsing), not the number of documents BizTalk Server has stored in the Shared queue checkpoint. The number of documents that are stored in the Shared queue checkpoint is essentially equal to the Documents Processed/sec counter. | BizTalk Messaging Services
 | Synchronous Submissions/sec, Asynchronous Submissions/sec | Indicates how quickly the Submit method and/or the SubmitSync method calls occur. Because each interchange can contain any number of documents, this counter is not useful for determining documents processed. If pass-through (processing interchanges without parsing them) is being used exclusively, this is the counter you need to monitor to determine inbound performance. | BizTalk Messaging Services
Message Queue | Messages in queue | This number should not get extremely large (over 50,000) because it will cause excessive memory use on the Message Queue server and degrade the performance of the entire system. | Message Queuing transport service
System | Processor Queue Length | This counter displays the number of threads waiting to be executed in the queue that is shared by all processors on the system. If this counter has a sustained value of two or more threads, the processor is degrading the performance of the entire system. | All
 | Context switches/sec | If this is a high number on BizTalk Server, it could be because send and receive functions are running on the same server. If this is the case, consider separating the send and receive functions to separate servers. | All
Processor | %Processor Time | If the value of this counter is high, while the network adapter card and disk I/O remain well below capacity, the processor is affecting performance. On a multiprocessor computer, examine this counter to identify any imbalance. Additionally, while peak utilization can be 100 percent, sustained utilization should be below this value. All server elements can be scaled horizontally. | All
Web Service | Get or post requests/sec | Indicates the volume of files being received through the HTTP get/post methods. | HTTP transport service

There are no counters specific to the SMTP transport service listed because there are a variety of SMTP transport service products available. Regardless of the SMTP transport service being used, monitor the volume of messages sent to and from BizTalk Server. Monitoring the counters listed in the table enables you to identify performance degradation. Because all the components work together to determine the health of a system, do not make drastic changes to your system configuration based on the poor performance of one.

Data obtained from performance monitoring is also useful for identifying symptoms that can contribute to problems. For example, a high amount of disk activity might indicate that SQL Server is writing a large amount of data to disk, but it might also indicate that the system is often paging to disk. Excessive disk paging typically indicates that memory is too low. In this case, the disk activity is the indicator of a problem, but not the problem itself.

Related Topic

Scaling BizTalk Server


Improving the Architecture

By identifying areas that affect performance, you can refine the system architecture to achieve optimal results. For example, hardware might need to be upgraded, or different components of BizTalk Server might need to be moved to separate servers. Additionally, you might need to adjust BizTalk Server settings. For more information about adjusting settings, see Optimizing Server Properties.

Ensure that changes are made methodically. After implementing a change, such as adding CPUs, changing a setting, or separating functionality to separate servers, document the change, and then test the new configuration to determine if performance has improved. If the new configuration enhances performance, then you can continue to modify the configuration. However, if the new configuration is degrading performance, reconfigure the system to its previous state, and analyze the data to determine what might be contributing to the problem.

Related Topic

Evaluating the Performance of a Configuration


Maintaining Performance

To maintain performance, create an ongoing maintenance plan to ensure the health and future performance of BizTalk Server. BizTalk Server will most likely process increasing numbers of documents over time. Although the initial BizTalk Server architecture may have performed well, if the number of transactions has increased over time, it might not be capable of sustaining the same level of performance unless the system architecture or configuration is modified. Hardware failures, or out of memory conditions, also can affect the performance of a system.

The following topics are covered in this section:

  • Creating a Performance Maintenance Plan

  • Using Application Center 2000


Creating a Performance Maintenance Plan

A successful monitoring plan includes:

  • A detailed plan of which counters to monitor. For example, there are several Windows 2000 System Monitor counters that contain valid thresholds to monitor, and possible interpretations of the problems that might be indicated by the thresholds. Additionally, you can also monitor application-level problems such as whether SQL Server queries should return valid data or return hardware problem conditions.

  • Identifying processes for resolving performance issues. For example, a Windows 2000 Event-Log message might be written, an e-mail notification might be enabled, or a custom program might start a series of events.

  • Defining which performance thresholds generate a notification. For example, a monitoring tool might be configured to write an event to the Windows 2000 Event Log if the CPU reaches 90-percent use capacity. However, if the CPU stayed at 90-percent use capacity for more than 5 minutes, an e-mail message might be sent. Defining different actions for different problem-severity levels depends on the monitoring tool that you use.

  • Defining the course of action in response to events published in the Windows 2000 Event Log. Windows 2000, BizTalk Server 2002, SQL Server, and native Microsoft transport services, such as Message Queuing and HTTP, write events to the Windows 2000 Event Log. This Event Log contains valuable information that might indicate impending problems on one of the servers in a BizTalk Server system. If addressed early, you can avoid a system failure that would degrade the performance of the overall system. A plan should include the frequency at which the logs are monitored and archived, and include the personnel responsible for the tasks. Microsoft Operations Manager (MOM) can be used to accumulate the logs from multiple servers and write them to a database for consolidated analysis. For more information about Microsoft Operations Manager, see About Microsoft Operations Manager.

  • Determining the required tools for performance monitoring. The built-in Windows 2000 System Monitor tool examines performance counters and can take action when a predefined condition occurs. For more information about configuring System Monitor alerts, see "Setting up a monitoring configuration" in Windows 2000 Help. Additionally, Microsoft Application Center 2000, as well as a number of third-party tools, perform this functionality with additional features such as logging to a database and performing application-level tests.


Using Application Center 2000

Microsoft Application Center 2000 contains a tool called Health Monitor. Health Monitor supercedes the functionality of the Windows 2000 Event Log and system monitor tools. It allows administrators to set up monitors. These monitors include checking TCP/IP, performance monitor counter thresholds, Event Log errors, and Windows Management Instrumentation (WMI) events. Conditions can be configured for these monitors so that when certain criteria are met. For example, when a threshold of 90 percent on a CPU is met or exceeded, an action occurs such as a taking a server offline or sending an e-mail message to an administrator. These tools can be used to proactively monitor and maintain the performance of BizTalk Server 2002.

Important

  • Do not replicate the default XLANG Scheduler application or any COM+ applications that host XLANG schedules. If Component Load Balancing is used, these COM+ applications must be installed on each server. You can replicate COM components that are bound to XLANG schedules.


Scaling BizTalk Server

Once you have optimized performance by optimizing your system settings and BizTalk Server, you might still experience bottlenecks due to high processor utilization. At this point, to achieve higher performance, it will be necessary to scale your BizTalk Server solution. There are two ways you can scale your BizTalk Server configuration. You can scale vertically (scale up) by increasing the number of processors and the amount of memory each server uses, or you can scale horizontally (scale out) by adding more servers to your BizTalk Server configuration.

It is highly recommended that you distribute key components across multiple servers. The key components of BizTalk Server 2002 include:

  • BizTalk Services. These services include BizTalk Messaging Services and BizTalk Orchestration Services. For more information, see BizTalk Messaging Services and BizTalk Orchestration Services.

  • Databases. These databases include the BizTalk Messaging Management, Tracking, Shared Queue, and Orchestration Persistence databases.

  • Transport services. The transport services include HTTP, File, SMTP, and Message Queuing. Each component has unique scaling requirements.

The following topics are covered in this section:

  • Scaling BizTalk Server Vertically

  • Scaling BizTalk Server Horizontally

Related Topics

Managing BizTalk Server Databases

Managing the BizTalk Messaging Management Database

Persistence

Set Transport Properties

Shared Queue Database

Tracking Database


Scaling BizTalk Server Vertically

By using multiple processors and significant memory, you can vertically scale (scale up) BizTalk Server 2002. Scaling BizTalk Server vertically requires fewer servers and simplifies site management, but is more costly than scaling a system horizontally or improving software architecture. In addition, once capacity on existing hardware is maximized, you must begin to scale the system horizontally.

The following topics are covered in this section:

  • Scale Up BizTalk Server

  • Scale Up the Databases

  • Scale Up the Transport Services


Scale Up BizTalk Server

To scale BizTalk Server 2002 vertically, the following steps are recommended:

  • Increase the processor size (such as the Pentium III and its Xeon derivatives with large level II caches).

  • Use symmetric multiprocessing (SMP) servers that accommodate up to eight CPUs.

  • Use a faster disk system.

  • Decrease file I/O and network bottlenecks. For more information, see Tuning the Performance of Your BizTalk Server Architecture.

Recommended solutions for scaling BizTalk Server vertically

To achieve optimal performance with BizTalk Server, the following are recommended:

  • A multi-processor PIII Xeon MHz processor system (the highest MHz possible for maximum performance), capable of being upgraded to eight CPUs.

  • A 1- to 2-MB L2 Processor Cache (increases parsing performance).

  • 1 GB of RAM (more if an organization is processing multiple megabyte documents).

  • Multiple 100 Mbps (megabits per second), or greater, network cards connected to 100 Mbps switch ports to increase network I/O throughput.

  • Multiple disks and controllers for Message Queuing and Distributed Transaction Coordinator (DTC) file and log operations. Write DTC log operations to a central remote server to offload file I/O contention on the local BizTalk Server.

  • Configure the disks as RAID 0 and RAID 1 for better performance on the Shared Queue database and Message Queuing.

  • Use multi-homed network interface cards (NICs) in the BizTalk Servers to separate HTTP processes from the dedicated Microsoft® SQL Server™ processes of the Shared Queue and BizTalk Messaging Management databases. Also, consider using a switch network to reduce the traffic to the network card.

  • These recommendations assume that BizTalk Server is running on a dedicated server. If the BizTalk Services are sharing the server with other application services, additional hardware is recommended.


Scale Up the Databases

To vertically scale the databases, you must determine the disk configuration. To determine the disk configuration, you must consider throughput, fail-over, and cost.

The following table identifies the options available and compares each option relative to each other.

RAID level | Cost | Effective disk utilization percentage | Speed | Fault tolerance
0 (Striping) | Low | 100 | Fast | Low
1 (Mirroring) | High | 50 | Medium | High
5 (Striping with parity) | Moderate | Effective disk space is the total space of all disks in the array combined minus 1 (for parity) | Slow | Moderate (only because performance degrades with a failed disk)
0 + 1 (Mirroring an array of stripped disks) | High | 50 | Fast | High

To achieve optimal performance, it is recommended that you install an efficient caching Redundant Array of Independent Disks (RAID) controller with a fast CPU and a high amount of RAM that is non-volatile. You can also combine multiple RAID levels to achieve the performance you want. For example, RAID 0 provides the best performance, but does not provide fault tolerance. RAID 1 provides the best fault tolerance, but does not provide the best performance (due to writing data to one disk, as opposed to multiple disks, concurrently). To achieve optimal performance, you can combine RAID 1 and RAID 0 by mirroring an array of RAID 0 disks.

Notes

  • RAID 5 does not meet or exceed the speed or cost of any other RAID level. RAID 5 provides key advantages, but is slower when writing data to disk than RAID 0 or RAID 1.

  • For any strategy, the number of available disk controllers is critical. You can significantly improve overall performance by using one disk per controller. When configuring disks, effectively using disk channels is equally important. Disk channels are disks that share the same controller. These disks may be configured as stand-alone disks, or configured to run as part of an array. For example, if there are 10 disks in a server, 5 disks each in two arrays, and each array is connected to its own controller, there would be 2 disk channels.

Ideally, the BizTalk Messaging Management, Shared Queue, Tracking, and Orchestration Persistence databases should be on separate disk channels, as this improves access to each of the databases. However, if your organization's system environment requires that the databases reside on individual servers, it is important to understand the use of each database when planning for this deployment scenario:

  • The BizTalk Messaging Management database contains all the configuration information, such as organizations, server groups, servers, channels, and messaging ports, for BizTalk Server. This information is read and cached in Microsoft SQL Server memory. This database receives the least activity of the four databases and can reside on the same disk channel as one of the other three databases if necessary.

  • The Shared Queue database manages the data for all the queues. Every document that uses asynchronous communication is sent to and stored in the Shared Queue database. When BizTalk Server is ready to handle the document, it is removed from the Shared Queue database for processing. Because this database manages all transactions, data is written to and read from the Shared Queue database frequently.

  • The Tracking database tracks documents that pass through the server, either individually or in batches. This database stores both the data and its logging information. Therefore, data is often written to the Tracking database, but data is rarely read from the database.

  • The Orchestration Persistence database stores the structure of the XLANG schedules, progress of activated XLANG schedule instances, and messages that are sent or received when an XLANG schedule instance begins or completes a transaction, the system is shut down, or when the XLANG schedule instance is dehydrated.

    Note

    • The most heavily used databases are the Tracking and Shared Queue databases. It is recommended that they be distributed between two servers for optimal load balancing.

Recommended optimization to vertically scale the databases

Consider the following for optimal performance of BizTalk Server databases:

  • A multi-processor PIII Xeon MHz processor system (the highest MHz possible for maximum performance), capable of being upgraded to eight CPUs.

  • 1 GB of RAM (more if an organization is processing multiple megabyte documents).

  • Optimize the underlying Microsoft SQL Server databases and logs based on standard database best practices. For more information about SQL Server, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.

  • If you initially plan to complete only a few transactions, you can install the databases on the same disk I/O channel. As more transactions are being processed, add disks and/or controllers to a server and move the databases to these new disk I/O channels. Additionally, an individual database can be moved to a new server. For more information about scaling the databases horizontally, see Scale Out the Databases.

  • If the CPU capacity exceeds 80 percent, add additional CPUs.

  • If disk queue length averages more than 1, or if disk I/O utilization approaches 100 percent, add additional physical disks.

  • Install the database on its own dedicated disk I/O channel.

  • Purchase disks with the fastest access times, and controllers with the highest throughput.

  • Consider RAID 0 and mirror it to obtain fault tolerance.

To optimize the BizTalk Messaging Management database:

  • 29Install the database on its own server or on its own disk channel.

  • If an organization processes a high volume of data, consider placing this database on its own disk I/O channel so as not to hinder the performance of the Shared Queue or the Tracking databases.

To optimize the Tracking database:

  • Add more physical disks and additional disk space than currently exists on the Shared Queue database.

  • Estimate the average document size for a single transaction. Multiply the document size by the number of times the document will be logged to the Tracking database. This estimate suggests the amount of document storage space required per document in the Tracking database. Multiply the document storage space value by the throughput requirement to determine the amount of space needed before the Tracking database becomes full. Ensure that the Tracking database has adequate space to accommodate logging an average document size.

  • Install this database on its own disk I/O channel due to the high volume of data that is written to it. A separate disk I/O channel is particularly important in heavy transaction environments.

  • Select the minimum amount of tracking necessary for your system.

    Note

    • There is size limit for tracking interchanges and documents, which if exceeded, greatly affects the performance of BizTalk Server. For more information about the size limit, see Interchange and document size limit.

To optimize the Orchestration Persistence database:

  • Because data is written to and read from this database frequently, the database should have a dedicated disk I/O channel. It is best to purchase disks with the fastest access times, and controllers with the highest throughput, if possible. Consider RAID 0 and mirror it to achieve fault tolerance.

  • If the CPU capacity exceeds 80 percent, add more CPUs.

  • If the disk queue length averages more than 1, or if disk I/O utilization approaches 100 percent, add more physical disks.

Related Topic

Scaling BizTalk Server


Scale Up the Transport Services

BizTalk Server 2002 supports four transport services. Each of these transport services can be scaled vertically:

  • HTTP/HTTPS

  • File

  • SMTP

  • Message Queuing

The following topics are covered in this section:

  • Scale Up HTTP/HTTPS

  • Scale Up File

  • Scale Up SMTP

  • Scale Up Message Queuing


Scale Up HTTP/HTTPS

Receive

The HTTP receive function sends documents either to the File system or directly into BizTalk Server by calling the BizTalk Server Interchange object IInterchange::Submit() or SubmitSync(). The HTTP receive function supports both HTTP and HTTPS transport protocols. The HTTP receive function manages a configurable thread pool, which services the documents posted.

In high-volume environments, if Secure Hypertext Transfer Protocol (HTTPS) is used to receive documents, performance is degraded due to decryption processing. Depending on the security needs of an organization, data might need to be encrypted using HTTPS. This added level of security might affect the performance of BizTalk Server.

Send

Sending documents using the HTTP transport service creates the same security and performance issues as receiving documents using the HTTP receive function.

Recommended optimization to vertically scale HTTP/HTTPS

To optimize performance for the HTTP receive function and the HTTP/HTTPS transport service, which enhances the performance of BizTalk Server:

  • Increase the CPU MHz that is required for BizTalk Server (to accommodate the additional need for sending or receiving documents) and add additional CPUs until you achieve the performance level you want.

  • Apply best practices when using ASP pages with the send HTTP/HTTPS service. For more information about optimizing ASP pages and Internet Information Services, go to Internet Information Services Help (localhost/iisHelp) and click Active Server Pages Guide.


Scale Up File

Receive

Although performance is high when using a File receive function for business-to-business transactions, a File receive function is not secure for Internet-based transactions, and therefore is not widely used. However, for application-to-application transactions within a corporation, a File receive function can provide optimal performance without jeopardizing security. In addition, a File receive function can be used securely with external trading partners provided it is combined with another receive function, such as SMTP or HTTP. The SMTP or HTTP receive function can accept a document from a trading partner (using S/MIME or HTTPS for security) and write the file to an internal file system directory. Then BizTalk Server can use a File receive function to receive the document. This combination of transports might not increase performance, but will provide greater flexibility and security.

Note

  • Using S/MIME significantly degrades the performance of BizTalk Server.

Send

The security and performance issues detailed for a File receive function are also applicable for sending documents using a File transport service.

Recommended optimization to vertically scale the File receive function and File transport service

To optimize performance for the File receive function and File transport service, which enhances the performance of BizTalk Server:

  • Use a local file directory rather than a remote file directory to reduce network latency.

  • Use disk arrays to achieve high throughput. For more information about disk array speed and redundancy tradeoffs, see Scale Up the Databases.

  • Use disk controllers with READ caching when using the File receive function.

  • Use disk controllers with non-volatile WRITE caching when using the File transport service.


Scale Up SMTP

Receive

No native SMTP receive function is built into BizTalk Server 2002. An SMTP receive function can receive a document through an event-based mechanism and send the document to BizTalk Server. If an SMTP receive function exists, BizTalk Server accepts the MIME/SMIME-encoded document and prepares it for processing.

Send

The same security and performance issues listed in the inbound S/MIME and outbound HTTP/HTTPS sections are also applicable for sending documents using SMTP as a transport service. If a channel uses SMTP as a transport service in a messaging port or port, the processing server processes the document and sends it to the receiving application.

Note

  • BizTalk Server performance is significantly degraded if a digital certificate is needed to S/MIME-encode the outbound document.

Recommended optimization to vertically scale SMTP

To optimize performance for SMTP, which enhances the performance of BizTalk Server:

  • The performance level achieved depends greatly on the SMTP service that is used for receiving documents. An organization might have an SMTP server that is used to perform this function. However, if an SMTP server is not available and an organization chooses to use Microsoft Exchange Server or another third-party messaging system, the server might need a significant amount of additional hardware to maintain an adequate performance level for BizTalk Server. The SMTP server must be able to invoke an event-based mechanism that is capable of sending documents to BizTalk Server.

  • If an organization chooses to run BizTalk Server on a SMTP server, CPU performance will be impacted. To minimize the impact to performance, use a faster CPU.

  • If an organization uses Secure Multipurpose Internet Mail Extensions (S/MIME), BizTalk Server performance is significantly degraded. To reduce the overall performance impact of S/MIME to BizTalk Server, use faster CPUs.


Scale Up Message Queuing

Receive

Message Queuing generally uses a high volume of disk I/O to receive and send messages. Message Queuing is transactional, which is highly recommended to improve fault tolerance. However, it is transactional only on a local server. If Message Queuing is used to improve fault tolerance, an adequate number of disks must be installed on each BizTalk Server to handle the increased disk I/O.

Send

Sending documents by using Message Queuing creates the same security and performance issues as receiving documents by using Message Queuing.

Recommended optimization to vertically scale Message Queuing

To optimize performance for Message Queuing, which enhances the performance of BizTalk Server:

  • Use transactional queues (local queues on BizTalk Server, rather than remote queues, must be used for transactional queues to receive) and a fast disk I/O channel. Local queues do not need to query Microsoft® Active Directory™; however, a public message queue must query Active Directory. Therefore, reading data from and writing data to local message queues results in better performance. Non-transactional local queues can be used to achieve better performance. However, non-transactional local queues do not provide the same reliability offered by transactional queues. Additional memory is also required.

    Note

    • For more information about how to define hardware requirements for Message Queuing, see "Selecting Message Queuing server hardware" in Windows 2000 Server Help.
  • The maximum limit for Message Queuing messages is 4 MB. If documents exceed 4 MB, the Message Queuing transport service cannot be used. The Orchestration Persistence database has a 2-MB document size limit.

  • Message Queuing is database-intensive if journaling is used. Ensure that the standard rules for optimizing databases are applied when setting up Message Queuing transport services.

  • To maximize throughput, separate data and logs and use multiple disks and controllers.


Scaling BizTalk Server Horizontally

A successful BizTalk Server 2002 implementation uses both a vertical and horizontal (scale out) strategy to optimize the services. While scaling vertically minimizes the number of servers required, scaling horizontally provides the following benefits:

  • Heightened performance. Performance exceeds what could cost-effectively be accomplished on a single server.

  • Server fault-tolerance. With multiple servers in a group sharing the workload, when one server fails, the other servers in the group can pick up the load.

  • Separation and optimization of the different components. Performance of BizTalk Services, the databases, and the transport services can be increased.

Scaling hardware horizontally minimizes costs relative to scaling vertically. However, as site management complexity increases, your organization must begin scaling vertically.

The following topics are covered in this section:

  • Scale Out BizTalk Messaging Services

  • Scale Out the Databases

  • Scale Out the Transport Services

Related Topic

Scaling BizTalk Server


Scale Out BizTalk Messaging Services

BizTalk Messaging Services can be scaled horizontally by using server groups. Server groups are collections of individual servers that are centrally managed, configured, and monitored. For more information about adding and configuring server groups, see Groups and Servers.

Servers that are members of the same server group share the following:

  • A Shared Queue database that monitors activity in the BizTalk Server state engine.

  • A Tracking database that logs document activity and generates reports.

  • A BizTalk Messaging Management database that stores configuration information.

  • Receive functions.

  • All components that the server requires at run time, such as transport components and application integration components (AICs), as well as data translation, data encryption, and signing.

A BizTalk Server group does not provide a load-balancing mechanism for either receiving inbound documents or for facilitating document submission by using Distributed Component Object Model (DCOM). However, you can use Network Load Balancing with the HTTP receive function or Component Load Balancing (CLB) to distribute the workload among the different servers. BizTalk Server does provide multiple-server work processing. Once a document is sent to the Shared Queue database, any server in the group can process, serialize, and send it out. This functionality allows for one server in a group to send a document that another server processes.

An organization can use multiple server groups to:

  • Group similar transport services (HTTP or File).

  • Enhance security.

  • Categorize trading partners.

You can also use server groups to avoid duplicating organization, channel, and messaging port configurations. Server groups share databases. Configuration information for the organization, group, channel, and messaging port is stored in the BizTalk Messaging Management database. Therefore, two or more BizTalk Server groups can share the same BizTalk Messaging Management database.

Note

  • If two or more BizTalk Server groups share the same BizTalk Messaging Management database, each group must have its own Shared Queue, Tracking, and Orchestration Persistence databases, which are shared by all members of the group.

Recommended solutions for scaling BizTalk Server horizontally

To optimize BizTalk Server performance, you can separate transport services and receive functions and prioritize parsers.

Separate transport services and receive functions

By separating transport services and receive functions for BizTalk Server groups, you can achieve higher performance. The level of performance you can achieve depends on the number and size of the documents being processed and the complexity of the data translation. BizTalk Server provides separate thread pools for receiving and processing data. Separating transport services and receive functions reduces context switching by eliminating the need for the server to alternate between send and receive operations.

All servers process work-items by default, which involves picking up work from the Shared Queue database, processing it, and then sending it out using the transport service the channel is configured to use (process outbound work). This process degrades the overall performance of the CPU when you are also using receive functions and transport services because context switching must occur. Provided you use two or more servers, you can eliminate this degradation by enabling at least one server to function as a receive service. To configure a server to act as a receive service, you can use BizTalk Server Administration to disable the Participate in work-item processing functionality and create a new receive function for the server.

For more information about disabling the Participate in work-item processing functionality, see Configure a server in a group. For more information about setting up a File receive function, see Add a File receive function. For more information about setting up a Message Queuing receive function, see Add a Message Queuing receive function. For more information about setting up an HTTP receive function, see Add an HTTP receive function.

Note

  • For Message Queuing, transacted reads can be done only from local queues, so only one server can read from that queue.

BizTalk Server receives documents if one of the following conditions exist:

  • A receive function has been configured on the same server as BizTalk Server.

  • Any process has been configured to call the Submit method on the server where BizTalk Server has been installed.

Prioritize parsers

By prioritizing parsers, you can optimize the performance of BizTalk Server. BizTalk Server provides four data parsers:

  • XML

  • EDIFACT

  • X12

  • Flat file

When BizTalk Server receives a document, it attempts to parse the document in the order in the previous list. By moving the most commonly used parsers to the top of the list, you can improve the performance of BizTalk Server. For more information about configuring the parser order, see Configure the parser order for a server group.

The following topic is covered in this section:

  • Component Load Balancing


Component Load Balancing

Component Load Balancing (CLB) is a feature of Microsoft Application Center 2000. To use CLB, Application Center 2000 must be installed on the same server as Microsoft BizTalk Server 2002. CLB enables organizations to load balance the BizTalk.Interchange.1 component in the COM+ Services manager. CLB is a load-balancing mechanism for COM components. In a BizTalk Server environment, CLB provides the ability for an HTTP transport to use the Submit method to call a cluster of servers instead of a single server (to the sending application, the Submit method used to call the cluster still appears as a submission to a node).

For example, if you use a custom application, a single submission can go to any of the servers in the cluster. Without CLB, the custom application must be configured to send to one of the three servers. In the latter scenario, if the server that the custom application was configured to send to failed, the custom application would need to be reconfigured to send to a different server in the BizTalk Server group.

Important

  • CLB can be used only to activate XLANG schedules. All XLANG schedules must finish on the server where they started.


Scale Out the Databases

To horizontally scale the databases, install each database on its own server. In high-volume transaction environments, installing a database on a unique server enables the CPU, disk I/O, and memory resources of the server to be allocated to the appropriate database.

Recommended optimization for horizontally scaling the databases

To optimize database performance of BizTalk Server:

  • Use Xeon processors instead of Pentium III.

  • Install each database on a separate server with faster CPU. Do not install any of the databases on the same server as BizTalk Server 2002.

  • Install one persistence database on each server on your configuration.

  • Use multiple 100 Mbps (megabits per second), or greater, network cards connected to 100 Mbps switch ports to increase network I/O throughput.

  • For an organization that is processing a small number of documents, use a database that can be upgraded easily. If processing needs increase, move the Shared Queue database, Tracking database, and Orchestration Persistence database to their own servers.

  • For the Tracking database, install fast network hardware to compensate for the high volume of uncompressed data that is exchanged between BizTalk Server and the database.

  • When scaling out these databases, keep in mind that moving the BizTalk Messaging Management database is more difficult, as this database stores all of BizTalk Server base configuration information and information used by the servers for receive functions, and locations of other databases, among others. To move the BizTalk Messaging Management database, you would have to create a custom process for replicating all the information into your new database, and then manually change each server to point to the new location. Therefore, it is highly recommended that the server on which the BizTalk Messaging Management database is stored contain suitable disk space and memory available to cache the configuration as document processing needs increase.

Related Topic

Scaling BizTalk Server


Scale Out the Transport Services

BizTalk Server supports four transport services. Each of these transport services can be scaled horizontally:

  • HTTP

  • File

  • SMTP

  • Message Queuing

The following topics are covered in this section:

  • Scale Out HTTP/HTTPS

  • Scale Out File

  • Scale Out SMTP

  • Scale Out Message Queuing


Scale Out HTTP/HTTPS

Receive

The HTTP receive function can be horizontally scaled by using a Web cluster. For example, a trading partner can send a document to one address, but the submission can be routed to any server in the cluster. Web clusters are a feature of the Network Load Balancing service included with Microsoft Windows 2000 Advanced Server. For more information about configuring Network Load Balancing, see Windows 2000 Advanced Server Help.

To improve the performance of BizTalk Server, you can configure a Web cluster to distribute the incoming documents across the servers configured with HTTP receive functions. The HTTP receive function then calls the submit method to place received documents into a file directory or a message queue.

Send

Horizontally scaling the send HTTP/HTTPS transport service is an inherent feature of using multiple servers in a group that are configured to participate in work-item processing. The HTTP/HTTPS send functionality cannot be separated from the BizTalk Server that processes documents because sending functionality is used on every server in the group that is configured to participate in work-item processing.

Recommended optimization for horizontally scaling HTTP/HTTPS

To optimize the HTTP/HTTPS transport service, which enhances the performance of BizTalk Server:

  • Create a load-balanced group of BizTalk Servers. This will further enhance the performance of the receive HTTP/HTTPS transport because it provides horizontal scaling redundancy. For more information about using Network Load Balancing to create a Web cluster, see Windows 2000 Advanced Server Help.

  • Work with your business partners to apply best practices when using ASP pages with the send HTTP/HTTPS service. For more information about optimizing ASP pages and Internet Information Services, go to Internet Information Services Help (localhost/iisHelp) and click Active Server Pages Guide.


Scale Out File

Receive

Although dedicating a BizTalk Server for the File receive function can minimize performance impact to the disk I/O, network latency will impact performance when attempting to retrieve the file. This can be solved by placing the files on a network share with a fast card, or by writing to a local directory on one of the servers and then having all the servers with a File receive function read from it.

Send

Scaling horizontally is accomplished with multiple servers in the group processing documents and then sending them to the File transport service. Performance will depend on whether or not BizTalk Server is used as the receive function, or whether or not BizTalk Server is configured as a separate server.

Recommended optimization for horizontally scaling a File receive function or File transport service

To optimize a File receive function or File transport service, which will enhance the performance of BizTalk Server:

  • Place the files on a network share with a fast card, or write to a local directory on one of the servers and then have all the servers with a File receive function read from it.

  • Configure a receive function to run on every server in the group that is polling the same File receive function to ensure that all servers in the group are retrieving documents for processing. File receive services are configured by default to run on a server within a group. Therefore, if you have five servers in a group and you configure a File receive function to run on one server in the group, when a File receive function is polled at \\receiveserver\receivelocation, only the one server of the five retrieves files for processing. This limits the number of document-processing servers to one for the entire group. The remaining four servers are not capable of retrieving files from the receive function to parse. For more information, see Add a File receive function, and follow the steps to create a File receive function on each server in the group, making sure you use the same polling location for all the receive functions.

  • Allow more servers to participate in work-item processing. Because sending files and receiving files are different processes, all servers in the group that are configured to participate in work-item processing send out files. Horizontal scalability of the File transport service is based only on the number of servers in the group that are configured to participate in work-item processing.


Scale Out SMTP

Receive

SMTP can receive documents from BizTalk Server, but it cannot send documents to BizTalk Server. To send a document to BizTalk Server, your SMTP solution must use the Submit method in order for a File or Message Queuing receive function to be able to process the document. The SMTP hosts, which are capable of providing these event-based mechanisms (Microsoft Exchange Server or a third-party messaging server), typically use a high volume of hardware resources. Therefore, adding this functionality to a server will degrade its ability to process documents. For more information, see the documentation for you SMTP solution.

Send

Lightweight SMTP transport services that do not have event-based mechanisms can be used for sending documents using SMTP. The SMTP transport host sending the document simply acts as a relay agent. The outbound SMTP host is configured at the group level, not at the server level. Therefore, if the SMTP transport exists on one server in a group, the server containing the SMTP transport service would use it to send outbound documents. All other servers in the group would use the same server for SMTP outbound.

Recommended optimization for horizontally scaling SMTP

To optimize SMTP, which will enhance the performance of BizTalk Server:

  • Configure the SMTP host to execute on a separate server from the BizTalk Services (for send and receive functionality). In most cases, an organization will have an SMTP host on its network that can be used for send and receive functionality.


Scale Out Message Queuing

Receive

You must decide whether to have the Message Queuing receive function on the same server as BizTalk Server, or to install it on a separate server. If you are using a transacted queue, the Message Queuing receive function must reside on the same server. However, if you are not using a transacted queue, the Message Queuing receive function can reside on a separate server. You must decide whether to incur the affects on performance by having the disk I/O on the local BizTalk Server or the network latency of the multiple server communication. In the latter example, the need for disk I/O would still exist, but it would exist only on the remote server instead of the local server. For more information about how to define hardware requirements for the Message Queuing service, see "Selecting Message Queuing server hardware" in Windows 2000 Server Help.

Send

Sending documents by using Message Queuing creates the same security and performance issues as receiving documents by using Message Queuing. However, you can do transacted WRITES to a remote queue.

Recommended optimization for horizontally scaling Message Queuing

To optimize performance for Message Queuing, which will enhance the performance of BizTalk Server:

  • Message Queuing is a disk-intensive process. To optimize Message Queuing, use a non-transacted queue.


Administering Servers and Applications

The administration features provided by Microsoft® BizTalk™ Server 2002 help administrators to efficiently and effectively administer all installations of BizTalk Server 2002. There are four areas of administration in BizTalk Server:

  • Server administration

  • Application administration

  • Programmatic administration

  • Database administration

This section covers server and application administration. For more information about programmatic and database administration, see BizTalk Server Administration Model.

BizTalk Server Administration provides a central user interface (UI) from which you can:

  • Add and manage servers installed with BizTalk Server in server groups.

  • Configure server group properties, such as the location for the Shared Queue and Tracking databases.

  • Configure and manage receive functions.

  • View and manage queues.

Application administration includes configuring and managing the COM+ applications that host XLANG schedules, the default XLANG Scheduler application, and the Orchestration Persistence database.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Server Administration, see About BizTalk Server Administration.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Server Administrator Tasks.

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Server Administration Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk Server Administration.

Related Topics

BizTalk Server Administration Model

BizTalk Orchestration Services


About BizTalk Server Administration

This section provides detailed conceptual information that is essential to understanding BizTalk Server Administration. It covers administrative tasks such as creating server groups, defining receive functions, and creating databases to manage, view, and log document activity in Microsoft BizTalk Server 2002.

The following concepts are covered in this section:

  • Groups and Servers

  • BizTalk Server Administration Environment

  • Administration Cache

  • Managing BizTalk Server Databases

  • Handling Server Errors

  • Receive Functions

  • Using Queues

  • Administration Privileges


Groups and Servers

In a data-exchange environment that supports the processing of a large number of documents, scale out solutions might require multiple servers and databases to meet processing demands. At the same time, businesses must have a way to centralize and manage document exchange to reduce the total cost of ownership of the solution by making it easy to manage.

Microsoft BizTalk Server 2002 provides both scale out and centralized management by assembling servers into groups and managing and configuring these server groups by using BizTalk Server Administration.

The following topics are covered in this section:

  • BizTalk Server Groups

  • Relationship Between Groups and Servers

  • Group Status States

  • BizTalk Servers


BizTalk Server Groups

A server group is the key organizing principle in BizTalk Server Administration. Server groups are collections of individual servers that are centrally managed, configured, and monitored.

Servers in a BizTalk Server group have in common:

  • A Shared Queue database that persists all documents until they are successfully processed.

  • A Tracking database that is used to log document and interchange activity and to run reports.

  • Receive functions.

  • All components that the server requires when processing documents and interchanges, such as transport components and application integration components (AICs).

A central BizTalk Messaging Management database manages multiple groups and servers. Thus, all groups and servers defined within a single BizTalk Server implementation share the same configuration information. This configuration information specifies the document-processing logic for the servers.

You must specify the same BizTalk Messaging Management database for each server installation so that you can remotely administer each server and group from the administration console. Also, if you are setting up multiple server groups for scalability and improved performance, you must use only one central BizTalk Messaging Management database. Otherwise, these servers cannot share the same BizTalk Messaging Management configuration.

Related Topics

Add, Delete, and Configure a Server Group

BizTalk Servers

Receive Functions

Relationship Between Groups and Servers

Using Queues


Relationship Between Groups and Servers

Each installation of BizTalk Server 2002 must have at least one server group. The relationship between groups and servers is defined by the following:

  • An individual server can belong to only one server group.

  • All servers in a group use the same Shared Queue database.

  • Each receive function in a group must run on one of the servers in that group.

  • All servers in a group share the same components, such as transport components and application integration components (AICs), to process interchanges and documents.

The following illustration shows the relationship between server groups in BizTalk Server 2002.

Logical configuration of groups and servers

Servers 1 through 6 are installed with BizTalk Server 2002. Servers A through D are installed with Microsoft® SQL Server™ and are dedicated to database management. Although servers A through D are dedicated to either the Tracking database or the Shared Queue database, the BizTalk Messaging Management database can reside on one of these servers because it is typically small and is not processor intensive. For maximum throughput, it is strongly recommended that your Shared Queue and Tracking databases reside on two separate servers dedicated to those functions.

Important

  • All servers within a group must have the same version and language of BizTalk Server installed. If servers with different versions of BizTalk Server (BizTalk Server 2000, BizTalk Server 2000 Service Pack 1, BizTalk Server 2002 Enterprise Edition, or a different language version of BizTalk Server) are installed within a group, the databases will not function properly.

  • When adding a new server to a BizTalk Server group, this new server must have the same version of BizTalk Server prior to being added to the group.

Related Topic

Managing BizTalk Server Databases


Group Status States

BizTalk Server Administration enumerates server groups and specifies whether each group can connect to the Tracking and/or the Shared Queue database. When you click Microsoft BizTalk Server 2002, the group states appear under the status bar in the details pane. The group states are:

  • Connected. Specifies that the group is connected to the Tracking and Shared Queue databases.

  • Tracking connection failed. Specifies that the group is not connected to the Tracking database.

  • Shared Queue connection failed. Specifies that the group is not connected to the Shared Queue database.

  • Tracking and Shared Queue connections failed. Specifies that the group is not connected to the Tracking and Shared Queue databases.


BizTalk Servers

BizTalk Servers are computers on which BizTalk Server has been installed and configured. Each server in a server group hosts the appropriate BizTalk Messaging Services functionality—such as data translation, encryption, digital signing, and document tracking—to manage document exchange between other servers and applications that are external to the BizTalk Server group. Each server queues and dequeues incoming and outgoing documents to and from the Shared Queue database, respectively, calling the appropriate Component Object Model (COM) methods to transform, serialize, sign, encrypt or decrypt, and transport documents.

Depending on your business needs, you can configure all servers in a group to both receive and process messages. This allows you to add and remove servers in a group easily because they all perform the same functions. Or, for maximum performance, you can configure some servers in a group to be dedicated to receiving documents and others to be dedicated to processing documents.

The following topics are covered in this section:

  • Understanding Server Properties

  • Server States

Related Topics

BizTalk Server Groups

Relationship Between Groups and Servers


Understanding Server Properties

When you configure a server in a group, you must balance maximizing throughput and server performance. Your business needs, server capacity, and network bandwidth are some of the factors that influence how you configure server properties. It is highly recommended that you experiment with different combinations in a test setting that simulates your production environment to determine what works best for your installation. You can set and modify the following server properties in BizTalk Server Administration.

Maximum number of receive function threads allowed

The maximum number of receive function threads is set on a per-processor basis. The range for this option is 1 through 128. Adjust this number to optimize the performance of the receive functions that are running on the server. In most cases, increasing the number of receive function threads increases the throughput of the receive functions on the server.

Participate in work-item processing

When the Participate in work-item processing check box is selected, the server processes documents in the Work queue. When this check box is cleared, the server does not process any documents in the Work queue.

The primary reason for configuring a server to not participate in work-item processing is to dedicate the server to receiving messages as part of an overall strategy to optimize throughput. For example, consider the case where there are three servers in a BizTalk Server group, two processing servers and one receiving server. By dedicating server tasks in this way, throughput is optimized because the number of types of processing contexts and activities on the servers is minimized. Benchmark testing has shown this to be an effective approach to throughput optimization.

Maximum number of worker threads per processor allowed

The maximum number of worker threads is set on a per-processor basis. The range for this option is 1 through 128. Setting this value too low could cause a bottleneck in BizTalk Server in a high-traffic situation, reducing overall throughput. Setting this value too high can also result in less than optimal throughput due to the overhead of unused threads. It is important to vary this setting and measure throughput to determine the optimal setting for your BizTalk Server implementation.

The Maximum number of worker threads per processor allowed and the Time between BizTalk Server Scheduler calls settings are two factors that influence how much traffic there is to the Microsoft SQL Server databases. You can limit the traffic to the SQL Server databases by setting the number low for Maximum number of worker threads per processor allowed and higher for Time between BizTalk Server Scheduler calls. Likewise, you can increase the traffic to the databases by increasing the number for the maximum number of worker threads and decreasing the settings for the time between scheduler calls.

Note

  • Clear the Participate in work-item processing check box if you do not want to process any work items on this server. Do not set the Maximum number of worker threads per processor allowed option to zero.

Time between BizTalk Server Scheduler calls (milliseconds)

The range for the Time between BizTalk Server Scheduler calls area is 1 through 4,294,967,295. There is a thread that polls for available items in the Work queue. The Time between BizTalk Server Scheduler calls controls how often the thread polls the Work queue. If you do not receive a lot of data, keep this number high. If you receive a lot of data, you might want to decrease this number.

Related Topic

Configure a server in a group


Server States

BizTalk Server Administration enumerates the servers in a server group and returns the list of servers. BizTalk Server Administration can return the following states for servers under the status bar in the details pane:

  • Running. Specifies that the server is running.

  • Access denied. Specifies that you do not have Microsoft® Windows® 2000 Administrator privileges on a server.

  • Error. Specifies if a server registered with a server group has had BizTalk Server 2002 removed.

  • Stopped. Specifies if an administrator has stopped a server.

  • Unknown. Specifies if a server registered with a server group is unavailable for an unknown reason. When this occurs, it is likely that you have lost connectivity with the server.

Related Topic

Administration Privileges


BizTalk Server Administration Environment

The following topics are covered in this section:

  • BizTalk Server Administration User Interface

  • BizTalk Server Administration Shortcut Keys

  • Administration Features of a BizTalk Server Tools Installation


BizTalk Server Administration User Interface

BizTalk Server Administration—also called the administration console—is a Microsoft Management Console (MMC) snap-in that provides a visual representation of the Microsoft BizTalk Server 2002 components that a system administrator can manage. The left side of the administration console is called the console tree and consists of folders and subfolders that represent different items, such as server groups. The right side of the administration console is called the details pane and contains information about the item that is selected in the console tree.

Graphically, BizTalk Server is displayed as a sub-item of the Console Root on the left side of the administration console. Each server group configured in BizTalk Server is displayed in a separate subfolder and consists of the queues and receive functions for that group, as well as the names of servers in the group. Expand any item in the console tree to display additional details about the item in the details pane of the administration console. You can right-click any item to configure it, or to create new items.

Related Topic

Open BizTalk Server Administration


BizTalk Server Administration Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Server Administration. The following table is a quick reference to the Microsoft Management Console (MMC) shortcut keys.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server and Advanced Server Help, see "Using the keyboard to move the mouse pointer." For more information about MouseKeys in Windows 2000 Professional Help, see "Move the mouse pointer by using MouseKeys."
Press | To
F5 | Refresh BizTalk Server Administration. This shortcut key refreshes the current item highlighted in the console tree.
ALT+F4 | Close BizTalk Server Administration.
ALT+MINUS SIGN | Display the window menu for the active console window.
SHIFT+F10 | Display the Action menu for the selected item.
ALT+A | Display the Action menu for the selected item.
ALT+V | Display the View menu.
F1 | View online Help for the selected item.
ALT+ENTER | Display the Properties dialog box, if any, for the selected item.

Related Topic

Open BizTalk Server Administration


Administration Features of a BizTalk Server Tools Installation

The tools installation feature enables you to install the Microsoft BizTalk Server 2002 Microsoft Management Console (MMC) snap-in (administration console) on client computers that are not BizTalk Servers. When you perform a tools installation of BizTalk Server 2002 on a client computer, there are some features of the administration console that are different from the features available in a computer with a complete installation.

When installed on a client computer, the administration console enables you to remotely administer one or more BizTalk Server configuration databases from the same computer and user interface.

After the initial installation of the administration console onto a client, the BizTalk Messaging Management database to be administered by the client has not been determined. Therefore, the first time you use the administration console after installation, when you select the BizTalk Server 2002 node, the Select Management Database dialog box appears. In this dialog box, you select the remote management database to be administered by specifying the SQL database name and the Microsoft SQL Server where the database resides. You can change the database to be administered at any time. For more information, see Change the BizTalk Messaging Management database being administered in a tools installation.

The differences between a tools-only installation of the administration console and the installation of the console on a complete installation of BizTalk Server are as follows:

  • When selecting the BizTalk Server 2002 node in a tools-only console tree, the Action menu does not include the Properties option. In a tools installation, although you are able to view and administer different BizTalk Messaging Management databases and different BizTalk Server groups, you are not able to change the BizTalk Messaging Management database to which all BizTalk Servers belonging to the original database point.

  • The Properties dialog box of the selected BizTalk Server group will not display the Parsers tab.

  • Although you can manage existing receive functions from the administration console in a tools installation, you will not be able to select or modify their advanced properties or create new receive functions.

Notes

  • The administration console can also be selected in a custom installation. The features available in the tools installation will also be available in the custom installation.

  • When all the features are selected in a custom installation (thus making it a complete installation), the administration console features will be the same as in the complete installation.


Administration Cache

When you start Microsoft BizTalk Server 2002, all items in BizTalk Server Administration, such as server groups, server group properties, receive functions, and connections to the Shared Queue and Tracking databases, are stored in the administration cache. By default, all items in the cache are refreshed every 50 seconds, except for the server database connections and server properties. This means that if you change the general properties for a server group, such as the SMTP host or the reliable messaging reply-to URL, the changes are picked up within 50 seconds.

However, if you change any server properties, such as the Maximum number of worker threads per processor allowed, you must stop and restart the server on which you changed the configuration so the change can be stored in the cache. Or, if you change a connection to the BizTalk Messaging Management, Tracking, or Shared Queue database, you must stop and restart the servers in the group and shut down the BizTalk Server Interchange Application.

Related Topics

Configure general properties for a server group

Shut down the BizTalk Server Interchange Application

Start a server in a group

Stop a server in a group


Managing BizTalk Server Databases

The three databases associated with BizTalk Messaging Services are:

  • BizTalk Messaging Management database

  • Tracking database

  • Shared Queue database

The database associated with BizTalk Orchestration Services is:

  • Orchestration Persistence database

The BizTalk Messaging Management database stores information for all server configurations, including group and server settings, and receive functions. The configuration of these administration objects can be handled either through BizTalk Server Administration or programmatically using the BizTalk Server Windows Management Instrumentation (WMI) provider. In addition to the administrative configuration, the BizTalk Messaging Management database also stores all messaging configuration information for channels, messaging ports, and other messaging objects. The configuration of the objects is handled either by using BizTalk Messaging Manager or programmatically by using the BizTalk Messaging Configuration object model. For more information about configuring channels, messaging ports, and so on, see Using BizTalk Messaging Manager or Messaging Services Reference.

The Tracking database keeps a log of all interchanges, documents, and receipts that are processed by BizTalk Messaging Services. For more information about the Tracking database, see Tracking Database. To configure tracking settings, see Configure tracking properties for a server group. To track specific fields or document instance data, see Set Channel Properties.

The Shared Queue database holds documents while they are being processed or waiting to be processed. Documents are later removed once they have been processed. For more information about the Shared Queue database, see Shared Queue Database.

The BizTalk Orchestration Persistence database stores the structure of XLANG schedules, the progress of activated XLANG schedule instances, and the messages that are sent or received while the XLANG schedule instance is running. For more information, see BizTalk Orchestration Services.

The following topics are covered in this section:

  • Managing the BizTalk Messaging Management Database

  • Managing BizTalk Server Group Databases


Managing the BizTalk Messaging Management Database

For most business implementations, there is one central BizTalk Messaging Management database that is used to configure multiple server groups, servers, channels, messaging ports, and so on. There are exceptions to this guideline, for example, third-party application service providers might need a separate BizTalk Messaging Management database for different types of customers, based on the particular business needs of each customer type. However, in most other cases, a central BizTalk Messaging Management database for all your BizTalk Server groups is all you need.

From time to time, it might be necessary to change the central BizTalk Messaging Management database. For example, when the server on which your BizTalk Messaging Management database resides needs maintenance. In this case, you must point all server groups to a replicated BizTalk Messaging Management database to keep your BizTalk Server enterprise running. It also might be necessary to move servers between one or more BizTalk Messaging Management databases.

For example, say you are a third-party vendor with three customers: A, B, and C. If the business from customer A decreased while the business from customers B and C increased, you could move the servers that were associated with the BizTalk Messaging Management database of customer A to the databases associated with customers B and C.

The following topics are covered in this section:

  • Changing the BizTalk Messaging Management Database

  • Removing Servers from the BizTalk Messaging Management Database

  • Moving Servers Between BizTalk Messaging Management Databases

  • Moving Remote Servers Between BizTalk Messaging Management Databases

  • Changing the Service Account Password


Changing the BizTalk Messaging Management Database

There are two ways to configure the BizTalk Messaging Management database:

  • Use the configuration options available during installation.

  • Use BizTalk Server Administration to change the server in the Microsoft BizTalk Server 2002 node.

If you want to centrally manage all your BizTalk Servers from a single server, during installation configure all servers to point to a central BizTalk Messaging Management database. If you do this, anytime you open BizTalk Server Administration on any one of those BizTalk Servers, the servers listed in the Microsoft BizTalk Server 2002 node point to the same BizTalk Messaging Management database and can be centrally managed. Once a collection of server groups point to a central BizTalk Messaging Management database, you typically do not need to change to a different BizTalk Messaging Management database.

An exception to this is when you need to bring that database offline for maintenance. In this situation, use BizTalk Server Administration to point all server groups in the Microsoft BizTalk Server 2002 node to a replication of the original central database. Do not temporarily point server groups to a different central BizTalk Messaging Management database that has other server groups associated with it. If you do, it might be difficult to return to your original BizTalk Messaging Management database configuration.

Note

  • To be able to change the BizTalk Messaging Management database, a user must be a member of the BizTalk Server Administrators group.

Related Topics

BizTalk Server Groups

Change the BizTalk Messaging Management database for a server

Configure the BizTalk Messaging Management database

Moving Servers Between BizTalk Messaging Management Databases

Security Guidelines


Removing Servers from the BizTalk Messaging Management Database

If you remove all BizTalk Servers from your BizTalk Messaging Management database, the contents of the database remain intact. Likewise, if you have more than one BizTalk Messaging Management database in your system and you remove all BizTalk Servers from a BizTalk Messaging Management database, the contents of the database remain intact. You can add new BizTalk Servers to the BizTalk Messaging Management database by running the BizTalk Server 2002 Database Setup Wizard and selecting an existing database on the Configure a BizTalk Messaging Management Database page. For more information about adding or changing the BizTalk Messaging Management database for a server, see Change the BizTalk Messaging Management database for a server.

Note

  • To remove servers from the BizTalk Messaging Management database, a user must be a member of the BizTalk Server Administrators group.

Related Topics

Change the BizTalk Messaging Management database for a server

Security Guidelines


Moving Servers Between BizTalk Messaging Management Databases

If you are planning to temporarily move a BizTalk Server from one BizTalk Messaging Management database to another, at least one other BizTalk Server must remain in place in one of the server groups within the original database. This enables you to easily restore the BizTalk Server to the original database. Otherwise, to add a new BizTalk Server to the database, you must run the BizTalk Server Database Setup Wizard and select an existing database on the Configure a BizTalk Messaging Management Database page. For more information about adding or changing the BizTalk Messaging Management database for a server, see Change the BizTalk Messaging Management database for a server.

Note

  • To move servers between BizTalk Messaging Management databases, a user must be a member of the BizTalk Server Administrators group.

Related Topics

Change the BizTalk Messaging Management database for a server

Groups and Servers

Security Guidelines


Moving Remote Servers Between BizTalk Messaging Management Databases

If you try to add a remote server to a BizTalk Messaging Management database, and that server was originally in a different central BizTalk Messaging Management database, the following error message appears in the Windows Event Log:

A new instance of the WMI class "MicrosoftBizTalkServer_Server" cannot be created in the BizTalk Server WMI provider. The <server name> server may already belong to a different BizTalk Server installation.

This error means that an attempt was made to add a remote server that was originally in a different central database. If this procedure was performed within BizTalk Server Administration, the administration console tries to determine if the remote server also belongs to a group in the remote central database. The administration console queries the Windows Management Instrumentation (WMI) provider of the remote server to make this determination. If the server does belong to a server group in the other central database, an error message from the administration console appears and explains that you cannot add a remote server that already belongs to a group in a different central database.

Note

  • To move remote servers between BizTalk Messaging Management databases, a user must be a member of the BizTalk Server Administrators group.

Related Topics

Error when moving a remote server to a different BizTalk Messaging Management database

Security Guidelines

About Windows Management Instrumentation


Changing the Service Account Password

Microsoft BizTalk Server 2002 supports only Microsoft® Windows® integrated authentication for databases access, which means that the BizTalk Messaging Services that run on BizTalk Server 2002 servers must run under an account that has permissions for both BizTalk Server and SQL Server. Although you can use a local computer account that has been properly set up to have access to all the servers in your environment, a domain account is highly recommended in all situations, especially when SQL Server and BizTalk Server reside on different servers, because this simplifies administration.

BizTalk Server provides a command line utility to change the password any time the password for the service account that is used by BizTalk Messaging Services changes, thus eliminating having to change the password on each server. This command line utility can also be used to change the account the BizTalk Messaging Services run under.

The form of the command line syntax is:

BTS_SvcPW {/? | {/s:<BTM SQL Server Name> /d:<BTM Database Name> {/u:<domain>\<user name> [/n:<domain>\<user name>] | /n:<domain>\<user name>} /p:<new password>}}

Where:

[] = Specifies that content is optional

<> = Contains a variable string name

| = OR binary operator

The following table explains the behavior of the parameters that can be used in the command line.

Include | To
/? | Bring up usage help for the utility. If specified, it must be the only argument used.
/s:<BTM SQL Server Name> | Include the name of the SQL Server in which the BizTalk Messaging Management (BTM) database resides. This database contains the servers for which the user wants to change the BizTalk Server Messaging service account and/or password. This is a required argument in the command line utility.
/d:<BTM Database Name> | Specify the name of the BizTalk Messaging Management database residing in the specified SQL Server. This is a required argument in the command line utility.
/u:<domain>\<user name> | Specify the domain and user name that BizTalk Messaging Services are currently running under. This entry is required to validate that the password entered into this utility is valid for the current user. The password is only validated on the local server on which the utility is run. Only those BizTalk Messaging Services that are using this account can be changed. This is an optional argument in the command line utility.
/n:<domain>\<user name> | Specify the domain and user name that BizTalk Messaging Services will run under the next time it is started. If this argument is used, the password provided is validated against this account rather than against the account that BizTalk Messaging Services is currently using. This is an optional argument in the command line utility.
/p:<new password> | Specify the new password that BizTalk Messaging Services will use to log on the next time it is started. This is an optional argument in the command line utility. However, if it is not specified, the user will be prompted to enter a new password.

Using the BizTalk Messaging Management database specified by the /s and /d arguments, all of the servers using that configuration are enumerated. For those enumerated servers using the account specified by the /u argument, the password, and optionally the account itself, are modified per the other arguments in the command line.

If the /u argument is not provided, the /n and /p arguments are used to update all enumerated servers. The /n argument must be provided and all of the messaging servers in the BizTalk Server configuration database (as determined by the /s argument) will be modified to use the new account and password.

The BizTalk Server Messaging service account can be changed only to an account with access privileges to both SQL Server and BizTalk Server. An error message will appear if it is changed to an account that does not have enough privileges to access the databases. Verify that the new account has Log on as service rights. A password must be provided every time this utility is run. If one is not provided on the command line, the utility will prompt the user for it. Also, if the new password is not provided on the command line, the user will be prompted for it.

Notes

  • The usage help will also be shown if the user violates any of the usage syntax.

  • The argument qualifiers /s, /d, /u, /n, and /p are not case sensitive.

  • All changes take effect the next time the modified BizTalk Messaging Services are started.

  • A log file is created the first time the command line utility is used or if the original log file was deleted. Once the log file is created, additional uses of the command line utility are appended to the existing log file. The log file is located in \Program Files\Microsoft BizTalk Server\BTS_SvcPW.log.


Managing BizTalk Server Group Databases

Each server group uses two databases, the Shared Queue database and the Tracking database. The Shared Queue database holds all documents and interchanges that are submitted to Microsoft BizTalk Server 2002 for processing and transmission. The Tracking database tracks and stores incoming and outgoing interchanges for auditing, reconciliation, and dispute-resolution purposes.

To help you organize the logical configuration of your servers and groups when the databases for two or more different groups reside in the same Microsoft SQL Server, it is important to create unique names for the Shared Queue and Tracking databases that are associated with each server group. For example, if you have two server groups, one called Group1 and one called Group2, and the databases reside in the same SQL Server, label the databases for the first group SharedQueue1 and Tracking1, and label the databases for the second group SharedQueue2 and Tracking2.

Note

  • The BizTalk Messaging Management database is a different database than the Shared Queue and Tracking databases. This database is used to store information about the configuration of multiple groups and servers, as well as to store information about the configuration of BizTalk Messaging Services. It does not handle document and interchange transmissions or track document and interchange activities.

The following topics are covered in this section:

  • Shared Queue Database

  • Tracking Database


Shared Queue Database

All servers in a server group share a single Shared Queue database. All documents and interchanges that are submitted to the servers in a group are stored in the Shared Queue database until they are processed by BizTalk Server.

The Shared Queue database is graphically represented in BizTalk Server Administration as a series of queues that provide information about the progress of an interchange or document in BizTalk Server. Interchanges and documents are in one of the following queues while they are processed by BizTalk Server:

  • Work queue. A list of interchanges and documents that are currently being processed by BizTalk Server.

  • Scheduled queue. A list of interchanges and documents that have been processed by BizTalk Server and are waiting for transmission according to the service window. For more information about the service window, see the ServiceWindowInfo Property.

  • Retry queue. A list of interchanges and documents that are being resubmitted, as well as reliable messages that are awaiting receipts.

  • Suspended queue. A list of interchanges and documents that failed processing for a variety of reasons, including parsing errors, serialization errors, or transmission errors, or that lack a correct channel configuration.

If BizTalk Server is processing an interchange or document, it stops processing and rolls back the Shared Queue database under the following circumstances:

  • BizTalk Server cannot access the Shared Queue database. For example, BizTalk Server loses the connection to the Shared Queue database because the server that hosts the Shared Queue database failed.

  • SQL Server failures occur, such as timeouts, aborted transactions, and deadlocks.

The transaction is rolled back even if BizTalk Server stopped processing after the interchange or document was transmitted. When the Shared Queue database is available again, the label is removed for all documents that are marked as "In process." This means that the documents are processed again instead of being placed in the Suspended queue.

If you use transactional message queues or reliable messaging, the delivery of your interchange or document is guaranteed to be just once. If you use non-transactional transmissions, then BizTalk Server 2002 might send the same document twice under the circumstances described in this topic.

Note

  • To administer queues stored in the Shared Queue database, a user must be a member of the BizTalk Server Administrators group.

Related Topics

Configure connection properties for a server group

Groups and Servers

Manage Queues

Security Guidelines

ServiceWindowInfo Property

Using Queues


Tracking Database

All servers in a server group share a single Tracking database that stores all information related to interchange and document activity in BizTalk Server. The Tracking database is used to track the status of an interchange or document as it moves through the server. For example, if you want to verify whether an order was sent to a trading partner, you can query the Tracking database. This database can also be used to verify that interchanges and documents are successfully sent or received by BizTalk Server, or it can provide information for reports such as transmission times or receipt responses.

Defining document tracking and logging parameters for the Tracking database

In BizTalk Server Administration, you can select whether interchanges and documents are tracked. For more information about how to configure tracking settings for a server group, see Configure tracking properties for a server group. If you enable tracking, the following options are available:

  • Log incoming interchange. With this setting, you can specify that documents received by BizTalk Server are stored in the Tracking database. Stored incoming documents provide an activity record for dispute resolution. This is selected by default.

  • Log outgoing interchange. With this setting, you can specify that documents sent by BizTalk Server are stored in the Tracking database. This is selected by default.

  • Log the original MIME-encoded message. With this setting, you can specify that MIME-encoded documents are stored in the Tracking database in their original message format before they are decoded. This is not selected by default.

Related Topics

Configure connection properties for a server group

Configure tracking properties for a server group

Security Guidelines

Start a server in a group

Stop a server in a group

Using BizTalk Document Tracking


Handling Server Errors

You can configure error handling in Microsoft BizTalk Server 2002 at the server level through Windows 2000 Event Viewer, which is included in BizTalk Server Administration. The Windows 2000 Event Viewer appears in the console tree of the administration console.

Logging events

The Windows 2000 Event Viewer displays a log that contains information about hardware, software, and system problems. From the administration console, you can customize the Event Viewer to show application errors that are specific to BizTalk Messaging Services and the XLANG Scheduler, which makes troubleshooting for BizTalk Server efficient. For more information about customizing Event Viewer for BizTalk Server and XLANG Scheduler errors, see Manage Event Viewer.

For more information about Event Viewer, in Windows 2000 Server Help, in the Event Viewer chapter, see "Using Event Viewer."

Note

  • All application errors related to BizTalk Server 2002 are defined as BizTalk Server or XLANG Scheduler errors.

Related Topic

Manage Event Viewer


Receive Functions

When you need to receive documents from a receive location and submit them to Microsoft BizTalk Server 2002, you can configure receive functions to process the data. For example, if you need to receive documents from a business organization or application that cannot communicate directly with BizTalk Server through a COM interface, you can use a receive function to submit the documents to BizTalk Server. Or, if you need to receive from a message queue, you can use a receive function to submit the document to BizTalk Server. BizTalk Server 2002 supports three types of receive functions:

  • File

  • Message Queuing

  • HTTP

You can create a generic receive function for BizTalk Server 2002 in the administration console in which you define the receive function name, document definition, and so on. For more information about configuring receive functions, see Manage Receive Functions for a Server Group. For more information about advanced properties for receive functions, see Understanding Receive Function Advanced Properties.

The following illustration shows the relationship between the sending business application, the file system, and a generic BizTalk Server receive function.

Relationship between the sending business application, the file system, and a generic BizTalk Server receive function

Note

  • You can also configure submit calls programmatically to receive documents and submit them to BizTalk Server. For more information about submit calls, see Submitting and BizTalk Documents.

The following topics are covered in this section:

  • Available Receive Functions

  • Correlation Token

  • Custom Preprocessors

  • Multiple Instances of Receive Function Types

  • Understanding Receive Functions and Document Routing

  • Understanding Receive Function Advanced Properties


Available Receive Functions

Three types of receive functions are available in BizTalk Server: File, Message Queuing, and HTTP. Your business practices determine which type of receive function you use and when.

File receive function

A File receive function is activated when there is activity in the directory that the receive function monitors. To use a File receive function, you must be able to modify the directory. The File receive function removes the files from the directory and submits them to BizTalk Server 2002.

Message Queuing receive function

A Message Queuing receive function is activated based on activity in a message queue. This receive function extracts the interchange or document from the queue and submits it to BizTalk Server 2002.

When you define the polling location for the message queue, use a format name instead of a path. BizTalk Server is designed to work with unmodified Message Queuing application programming interfaces (APIs), and the API calls work only with the format name property. Use the following format name when you configure a Message Queuing receive function:

Direct=OS:<server name>\<queue name>

Note

  • For more information about Message Queuing and format name, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on the keywords "Message Queuing Services."

HTTP receive function

An HTTP receive function is an Internet Server Application Programming Interface (ISAPI) extension that provides an "out-of-the-box" utility for immediately receiving documents over Hypertext Transfer Protocol (HTTP) with minimal configuration and without the need to develop Web pages or additional dynamic-link libraries (DLLs).

The HTTP receive function submits documents either to the file system or directly into BizTalk Server through a COM call to the Submit method or SubmitSync method.

Related topics

Add a File receive function

Add an HTTP receive function

Add a Message Queuing receive function

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure a File receive function: General tab

Configure a File receive function: Services tab

Configure a Message Queuing receive function: General tab

Configure a Message Queuing receive function: Services tab

Configure an HTTP receive function: General tab

Configure an HTTP receive function: Services tab


Correlation Token

The HTTP receive function uses a correlation token to emulate the synchronous behavior on an asynchronous BizTalk Server submission. An example of how this is achieved is when a document is submitted to an ASP page in a perimeter network (also known as DMZ, demilitarized zone, and screened subnet). If the ASP page uses an HTTP receive function to pass the document to the other side of the firewall, a correlation token is used to monitor the progress of document processing and to determine when to return to the client that originally sent the document. Using the correlation token makes the asynchronous process appear synchronous to the client.

Note

  • The correlation token used by an HTTP receive function is not related to the Orchestration correlation process.


Custom Preprocessors

If you have documents that need to be processed before they are submitted to BizTalk Server, you can create a custom preprocessor and configure the receive function to call the preprocessor. For example, if you send compressed data and need to decompress it before submitting it to BizTalk Server for processing, configure the receive function to call the custom preprocessor to decompress the data.

Related Topics

Class identifier appears in the Preprocessor list

IBTSCustomProcess

Preprocessing Documents in a Receive Function


Multiple Instances of Receive Function Types

There can be multiple instances of a receive function. For example, if multiple business applications use a File receive function to submit documents and interchanges to BizTalk Server 2002, you can configure either a single instance or multiple instances of the File receive function.

Notes

  • Verify that each of the receive functions that you create has a unique name. You cannot assign identical names to receive functions.

  • For all HTTP receive functions running on the same server, it is recommended that you use only one dynamic-link library (DLL) or virtual directory. If multiple DLLs or virtual directories are used, you might see unexpected results. For more information about adding HTTP receive functions, see Add an HTTP receive function.

Related Topic

Manage Receive Functions for a Server Group


Understanding Receive Functions and Document Routing

When you configure a receive function, determine whether the documents received by the receive function are self-routing or non-self-routing. Self-routing documents contain all the necessary routing information; non-self-routing documents lack some or all of the routing information.

Self-routing documents

Self-routing documents have all routing information—the source organization identifier, the destination organization identifier, and the document definition—defined in the routing tags that are defined by the document specification or hard-coded in the document, as in the case of X12 and EDIFACT. Any document for which you can create a specification in BizTalk Editor can be configured as a self-routing document. Common types of self-routing documents are XML, X12, and EDIFACT. You do not need to configure any advanced properties in the receive function if a document is self-routing, unless you want to override the data provided in the document.

If the source or destination organization qualifiers or the document definition is missing from the document, it is placed in the Suspended queue. Additionally, if you do not specify a source or destination organization qualifier, BizTalk Server uses the default value of Organization Name as the organization qualifier and refers to the name of the organization stored in the BizTalk Messaging Management database.

Non-self-routing documents

Non-self-routing documents are missing all or some of the necessary routing information. When you configure the receive function, the following information must be defined on the Advanced tab of the receive function Properties dialog box or in the document to be supplied to the receive function:

  • Source organization identifier, destination organization identifier, and document definition

    —Or—

  • Channel

When you submit a document, BizTalk Server locates a channel to process the document. This can happen in two ways: either by supplying a channel name in the receive function or by supplying the source and destination organization identifiers and the document definition. These three properties help BizTalk Server locate the correct channel. Therefore, if you select a channel, the document definition and source and destination information options are unavailable because the channel supplies all the information that is needed to route the document.

Common types of non-self-routing documents are documents that come from multiple sources (open source) or are going to multiple destinations (open destination).

Configuring a receive function to manage documents from multiple sources

You can configure a single receive function that handles non-self-routing documents to receive a specific type of document from multiple sources. This is an open source scenario. The location of the source organization, the destination organization, and the document-definition information must be in the document or in parameters submitted along with the document.

For example, if you plan to receive purchase orders from multiple customers, but want them all sent to the same destination application, set the document definition and destination organization identifier properties in the receive function. When BizTalk Server parses the document, it locates the supplier organization identifier, combines this information with the parameters in the receive function, finds the correct channel, and then processes the document.

Related Topics

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Manage Receive Functions for a Server Group

Set source organization properties


Understanding Receive Function Advanced Properties

You can use advanced properties to configure special types of receive functions based on your business practices.

For example, you can define receive functions to submit:

  • Documents that have the Open source or Open destination property set.

  • 90Documents that have the pass-through property set.

  • Documents that specify a channel name.

  • Other types of non-self-routing documents.

Define the Openness property in a document

The following options define the openness of a document:

  • Not open. Specifies that the source and destination are both explicitly declared in the receive function or the document instance.

  • Open Destination. Specifies that the destination information is not explicitly declared in the messaging port. The destination is dynamically specified in the document instance or a submission parameter. You must configure the document definition and the source-organization identifier properties in the receive function or in the document instance in order for BizTalk Server to locate the correct channel.

  • Open Source. Specifies that the source information is not explicitly declared in the channel. Instead, the source is dynamically specified in the document instance. You must configure the document definition and destination-organization identifier properties in the receive function or in the document instance in order for BizTalk Server to locate the correct channel.

Configure receive functions with pass-through

A receive function configured with pass-through bypasses the parsing, decryption, signature verification, transformation, and decoding functions of BizTalk Server. Choose this option when you are sending binary large object data or other interchanges that do not require parsing, decryption, and decoding. If you configure a receive function with Submit with a pass-through flag set, you must specify a channel. Otherwise, BizTalk Server cannot process the document.

Envelope name

If you expect to receive an inbound interchange in a flat file, specify the envelope format in the receive function. The envelope points to a specification that tells BizTalk Server how to open and interpret the interchange. If you plan to receive multiple flat files in a single interchange, the individual flat files must be separated with a delimiter that is postfix or prefix. Infix is not supported. This must be set at the root node of the envelope specification and the document specification when you configure parse properties. For more information about setting parse properties for a flat file, see Set parse properties and browse to the "Standard: Custom, Structure Property: Delimited" table.

Channel name

Each interchange or document that is submitted to BizTalk Server requires a set of rules for how it is to be processed. The channel contains all the information that the server needs to process the interchange or document. All interchanges and documents that are processed by BizTalk Server must go through a channel. A channel is located in one of two ways.

The first way channels are located is when an interchange or document is submitted. BizTalk Server parses the document for the source and destination identifiers and the document definition. If this information is not in the document instance, BizTalk Server then looks at the receive function. Once the source and destination identifiers and the document definition are discovered, BizTalk Server determines which channels have the same document definition, source, and organization identifiers as the received document. When BizTalk Server finds a channel match, the document instance is processed.

The second way channels are located is when they are specified in the receive function. In this case the channel lookup is bypassed and the received document is processed faster.

Document definition, source organization, and destination organization identifiers

You can configure the document definition, source organization identifier, and/or the destination organization identifier when you receive non-self-routing documents. The routing information that is included in the document that you receive determines which of these properties you define in the receive function.

For example, if you receive multiple document types from the same source organization and you always send those documents to the same destination, you can configure the source and destination organization identifiers in the receive function and dynamically define the document definition in the document instance.

Related Topics

Create envelopes

Set envelope information properties

Set parse properties

Understanding Channels

Understanding Document Definitions

Understanding Envelopes

Understanding Organizations

Understanding Receive Functions and Document Routing

Using Envelopes for Inbound Processing


Using Queues

Microsoft BizTalk Server 2002 provides shared queue management capabilities in BizTalk Server Administration. BizTalk Server Administrators can move documents from any other queue to the Suspended queue. From the Suspended queue, documents can be deleted, resubmitted, or viewed, depending on the processing state of the document. BizTalk Server Administrators can sort and display error messages for documents in the Suspended queue.

The following queues are used to contain incoming and outgoing documents that are in various stages of routing and processing in BizTalk Server:

  • Work Queue

  • Scheduled Queue

  • Retry Queue

  • Suspended Queue

Note

  • Interchanges and documents appear in BizTalk Server Administration in the order of "first in, first out." That is, the oldest items in a queue appear first and the newest items appear last. Additionally, up to 15,000 interchanges and/or documents appear in a queue at a time. If there are more than 15,000 actual items in a queue, you must remove or resubmit current items in the queue so that newer items can be displayed. The queue count in the console tree—the number next to the queue in parentheses—represents how many actual items there are in the queue. You can resubmit or delete documents to remove them from a queue.

Related Topic

Manage Queues


Work Queue

The Work queue contains documents that are currently being processed by BizTalk Server. Transactions in the Work queue do not remain in the queue very long because they are processed upon arrival. BizTalk Server Administrators can select any document in this queue and move it to the Suspended queue.

Related Topics

Move documents to the Suspended queue

Using Queues


Scheduled Queue

The Scheduled queue contains work items that have been processed by BizTalk Server and are waiting for transmission based on the service window. BizTalk Server Administrators can select any document in this queue and move it to the Suspended queue. For more information about the service window, see the IBizTalkServiceWindowInfo interface object.

Related Topics

IBizTalkServiceWindowInfo

Move documents to the Suspended queue

Using Queues


Retry Queue

The Retry queue contains documents that are being resubmitted for delivery and documents that are waiting for reliable messaging receipts. You cannot tell the difference between the two types of transmissions. By default, failed transmissions are retried every five minutes for a maximum of three tries before they are moved to the Suspended queue. These numbers can be changed through BizTalk Messaging Manager or programmatically. For more information about changing the number of retries, see Set advanced configuration properties, or RetryCount Property and RetryInterval Property.

BizTalk Server Administrators can select any document in this queue and move it to the Suspended queue.

Related Topics

Move documents to the Suspended queue

RetryCount Property

RetryInterval Property

Set advanced configuration properties

Using Queues


Suspended Queue

The Suspended queue contains work items that have failed processing for a variety of reasons, including parsing errors, serialization errors, failed transmissions, or the inability to find a channel configuration. BizTalk Server Administrators can right-click any document in this queue to choose any of the following options:

  • View Error Description. Enables BizTalk Server Administrators to view error descriptions that indicate why the document was sent to the Suspended queue.

  • View Interchange. Enables BizTalk Server Administrators to view the contents of an interchange that has failed processing for a variety of reasons, including parsing errors or failed transmissions. View Interchange appears for the following states:
    • Initial

    • Custom component

    • Parsing

    • Encoding

    • Signing

    • Encrypting

    • Transmitting
  • View Document. Enables BizTalk Server Administrators to view the contents of a document that has failed processing for a variety of reasons, including serialization errors or the inability to find a channel. View Document appears for the following states:
    • Document validation

    • Channel selection

    • Field tracking

    • Mapping

    • Correlating

    • Serializing
  • Delete. Enables BizTalk Server Administrators to completely remove an entry from the Suspended queue. This action is not recoverable. After a document has been deleted from the Suspended queue, you cannot retrieve it.

  • Resubmit. Enables BizTalk Server Administrators to resubmit interchanges and documents to BizTalk Server for processing.

Suspended queue states

Interchanges and documents are placed in the Suspended queue for a variety of reasons. The following table explains the Suspended queue states, their associated error messages, and what action you might take in response.

Suspended queue state value | Error message | Error description and possible action
Channel Selection or Transmitting | Unexpected Error | There was an unexpected internal server failure. Resubmit the document.
Channel Selection or Transmitting | Unknown | The interchange or document was marked as "In process" by an inactive server. When the server was restarted, this item was automatically moved to the Suspended queue. There was probably a failure on the original server. Contact the system administrator for more information. When the problem is corrected, resubmit the document or interchange.
Channel Selection or Transmitting | Out of Memory | The computer on which BizTalk Server is running ran out of memory. Restart the server and resubmit all interchanges and documents in the Suspended queue.
Parsing | Parsing Failure | BizTalk Server was unable to parse the data. View the contents of the interchange to determine why BizTalk Server was unable to parse it. Resubmit the interchange using IInterchange or a receive function. For more information, see An interchange or document appears as binary data in the Suspended queue or Parsing errors.
Parsing | Missing Data | The information extracted from the incoming data did not contain enough information to locate a channel. View the interchange and find which data is missing. Resubmit the interchange using IInterchange or a receive function. For more information, see An interchange or document appears as binary data in the Suspended queue or Parsing errors.
Parsing | "expiresAt" Expired | The BizTalk Framework timestamp "expiresAt" expired. This document is no longer valid. For more information, see An interchange or document appears as binary data in the Suspended queue.
Channel Selection | No Channels Found | BizTalk Server was unable to find any channels that matched this document. Create a channel for the document, or correct the document and then resubmit it.
Channel Selection | Channel Removed | The channel associated with this document was deleted after the document reached the Work queue. Reconfigure the channel, or configure the document for a different channel and resubmit the document. —Or— Do not submit the document and delete it from the Suspended queue.
Field Tracking or Initial | Channel Missing | The channel specified by the receive function or submit call could not be found. Configure a channel or reconfigure the document and resubmit it.
Channel Selection | Channel Not Valid | The channel specified by the submit call was an open channel. Open channels are not valid for pass-through submit calls. Change the channel and resubmit the document.
Mapping | Mapping Failure | The map referenced by the channel is formatted incorrectly. Delete the document from the Suspended queue, correct the map, and submit the document as a new document.
Serializing | Serializing Failure | BizTalk Server could not convert the document to its native format. Resubmit the document.
Encoding | Encoding Failure | BizTalk Server could not encode this interchange. Resubmit the interchange.
Signing | Signing Failure | BizTalk Server could not sign this interchange. The certificate might have expired. See the Certificates Microsoft Management Console (MMC) snap-in for details. For more information about how to view the Certificates snap-in, in Windows 2000 Help, in the Manage Certificates chapter, see "Add the Certificates snap-in to the MMC console."
Encrypting | Encryption Failure | BizTalk Server could not encrypt this interchange. The certificate might have expired. See the Certificates Microsoft Management Console (MMC) snap-in for details. For more information about how to view the Certificates snap-in, in Windows 2000 Help, in the Manage Certificates chapter, see "Add the Certificates snap-in to the MMC console."
Transmitting | Transmission Failure | BizTalk Server could not deliver the interchange. Check the transport address in the channel. Correct the problem and resubmit the interchange.
Transmitting | Timeout Failure | BizTalk Server was unable to complete processing of this interchange before timing out. This could be because the transmission took too long. If you are using an unreliable transport, check to see if this interchange has been sent before you attempt to resubmit the interchange.
Transmitting | User Move | A BizTalk Server Administrator has moved this document to the Suspended queue. Resubmit the interchange.
Transmitting | Timestamp Expired | The BizTalk Framework timestamp "receiptRequiredBy" expired. This document is no longer valid.
Document Validation | Document Not Valid | The validation of the document against its specification failed. Look for the error in the Event Log for more information. Correct the schema and resubmit the document.
Field Tracking | Field Tracking Failure | BizTalk Server could not track the requested fields within the document. View the document to verify that the fields that you want tracked are present, or change the channel configuration for field tracking. Then resubmit the document.
Custom Component | Custom Component Failure | A custom component has failed. Troubleshoot the custom component or custom preprocessor and submit the interchange.
Correlating | Correlation Failure | There was a failure correlating this receipt.

Notes

  • In addition to checking the error messages in the Suspended queue, you can also check the Event Log for more information. For more information about the Event Log, see Manage Event Viewer.

  • Not all documents in the Suspended queue can be resubmitted. In some situations, you must delete the document and submit it again from the original application or organization.

Related Topics

An interchange or document appears as binary data in the Suspended queue

Manage Event Viewer

Manage Queues

Parsing errors

Understanding Receive Function Advanced Properties

Understanding Receive Functions and Document Routing

Using Queues


Administration Privileges

To view BizTalk Server Administration, you must be a member of the BizTalk Server Administrators group. If you are not logged on as a BizTalk Server Administrator, you cannot view items inside the Microsoft BizTalk Server 2002 folder. If you are a member of the BizTalk Server Administrators group, but you are not a member of the Microsoft Windows 2000 Administrators group, you can perform only the following tasks:

  • Add and remove server groups

  • View and modify group properties

  • Manage all queues and their entries

  • Add and remove receive functions

  • View and modify receive function properties

Additionally, if you are administering a server group that contains three servers, for example, Server_1, Server_2, and Server_3, you must have Windows 2000 Administrator privileges on all three servers. If the Windows 2000 Administrator privileges have been changed on Server_1, and you no longer have Administrator privileges, the administration console returns a list of all three servers associated with the group and lists the state of each server. The state of Server_1 is returned as Access Denied.

If you are a member of both the BizTalk Server Administrators group and the Windows 2000 Administrators group, you can perform the following additional tasks:

  • Add servers to and remove servers from a server group

  • View and modify server properties

  • View server status

  • Free interchanges on a server

In addition, you must also be a member of the SQL Server Administrators group in order to access the databases.

During setup, the user who runs the BizTalk Server installation is added to the BizTalk Server Administrators group. You can add other users to the BizTalk Server Administrators group. For more information, see Add users to the BizTalk Server Administrators group.


Why Perform BizTalk Server Administration Tasks

This section provides a quick reference about why you perform BizTalk Server Administration tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Open BizTalk Server Administration
 To perform most of the administration tasks.
  • Open Component Services
 To perform additional administration tasks.
  • Publish BizTalk Server 2002 in Active Directory
 To publish the availability of BizTalk Server in a distributed environment.
  • Delete BizTalk Server 2002 from Active Directory
 To remove the registration of that computer from Active Directory so that only those computers still running BizTalk Server are properly identified when you query Active Directory.
  • Add users to the BizTalk Server Administrators group
 To add new users that want permission to administer BizTalk Server.
  • Configure the BizTalk Messaging Management database
 To take the BizTalk Messaging Management database offline for maintenance.
  • Change the BizTalk Messaging Management database being administered in a tools installation
 To change the BizTalk Messaging Management database being administered from a client computer.
  • Refresh the administration console
 To view the current status of server groups, servers, receive functions, the number of items in a queue, and so on.
Add, Delete, and Configure a Server Group:
  • Add a server group
 To add a new BizTalk Server group when additional scale out is required. BizTalk Server groups are a key factor in the scalability of BizTalk Server. By creating additional server groups, you can increase throughput by partitioning processing across more computers.
  • Configure general properties for a server group
  • To change the SMTP host that a BizTalk Server group uses.

  • To change the URL the BizTalk Server group uses to receive reliable messaging receipts.

  • To modify how often the BizTalk Messaging Management object cache is refreshed.

  • To add and/or change the proxy server that the BizTalk Server group uses.
  • Configure connection properties for a server group
 To modify the Shared Queue and/or Tracking databases the BizTalk Server group connects to. Typically, these will only need to be modified when changing to another database or database server is required, such as part of a disaster recovery or backup regime.
  • Configure tracking properties for a server group
 To enable various levels of document tracking for the server group and to turn tracking on and off.
  • Configure the parser order for a server group
 To change the parser order or refresh the parser list from the registry. The parser list order can be altered, for example, to optimize throughput when all or most of the documents received are of a specific type. By placing the parser for that document type first in the list, BizTalk Server will process the documents faster by avoiding trying to parse with other parsers.
  • Delete a server group
 To remove a whole BizTalk Server group. For example, if overall throughput requirements are reduced, deleting one or more groups can free up the hardware resources for other purposes.
Add, Delete, and Configure Servers in a Group:
  • Add a server to a group
 To add a new server to an existing BizTalk Server group. In addition to adding groups to a BizTalk Server implementation, each group can have a variable number of servers associated with them. By optimizing the number of servers in the group against the processing power of the database servers in the group, throughput is maximized.
  • Delete a server from a group
 To remove a server from a BizTalk Server group. To move a server from one BizTalk Server group to another, you first need to delete it from the current group and then add it to the new group.
  • Configure a server in a group
 To modify the general properties of a server, such as the maximum number of receive function threads allowed, and whether the server participates in work-item processing. By creating receive functions that run on the server and marking the server to not participate in processing, the server can be optimized for receiving interchanges as fast as possible, thus contributing to the overall throughput.
  • Change the BizTalk Messaging Management database for a server
 To change the BizTalk Messaging Management database that a server uses. This is typically only necessary when a permanent change to another database is needed, such as during disaster recovery or when the existing database server is replaced by another database server.
Manage Servers in a Group:
  • Start a server in a group
 To start a BizTalk Server. This starts the BizTalk Server run-time services on the associated server so that it can participate in receiving and/or processing interchanges.
  • Stop a server in a group
 To stop a BizTalk Server. This stops the BizTalk Server run-time services on the associated server so that it will cease participation in receiving and/or processing interchanges.
  • Free interchanges from a server
 To free interchanges from a server so that the interchanges can be redistributed to other servers in the group if the original server is stopped or taken offline.
  • Configure disk caching
 To enable or disable disk caching. When disk caching is disabled, it avoids the loss of data during catastrophic failures such as power failures.
Manage Queues:
  • Move documents to the Suspended queue
 To move a document from the Work, Scheduled, or Retry queues to the Suspended queue. Typically, this is done if it is known that a specific message or group of messages need to be suspended due to some type of problem or exception condition either with the message itself, or with systems to which the message may be subsequently sent if not suspended.
  • View error descriptions
 To find out what error caused a document to be placed in the Suspended queue. This is provided primarily to support problem resolution scenarios.
  • View interchanges
 To view an interchange that has been placed in the Suspended queue. This is provided primarily to support problem resolution scenarios.
  • View documents
 To view a document that has been placed in the Suspended queue. This is provided primarily to support problem resolution scenarios.
  • Resubmit documents
 To resubmit a document that is currently in the Suspended queue. This is typically used to resubmit messages after the reason they were suspended has been addressed. For example, if a transport problem resulted in the suspension of a number of messages, resubmitting them after the problem has been addressed should result in successful transmission of the messages.
  • Delete documents
 To delete a document placed in the Suspended queue. This assumes that either the message is no longer needed, or that the message has been saved by the user.
Manage Databases for a Server Group:
  • Shut down the BizTalk Server Interchange Application
 To change a connection to the BizTalk Messaging Management, Tracking, or Shared Queue databases.
  • Remove the Tracking and Shared Queue databases
 To remove the Tracking or Shared Queue databases. Typically, this would only be done after BizTalk Server has been configured to use a different Tracking and/or Shared Queue database. If these databases are removed without first configuring BizTalk Server to use other databases, BizTalk Server will cease to function properly.
  • Manually restore the Tracking database
 If the Tracking database becomes corrupted or damaged. This presumes that a backup has been previously created from which you can restore the database.
  • Manually restore the Shared Queue database
 If the Shared Queue database becomes corrupted or damaged. This presumes that a backup has been previously created from which a restore can be done.
Manage Receive Functions for a Server Group:
  • Add a File receive function
 To create a File receive function.
  • Configure a File receive function: General tab
 To configure the general properties of a File receive function, such as the security information and to enable or disable the function.
  • Configure a File receive function: Services tab
 To modify the server on which the File receive function runs, the polling information, or the preprocessor that the File receive function uses.
  • Add a Message Queuing receive function
 To create a Message Queuing receive function.
  • Configure a Message Queuing receive function: General tab
 To configure the general properties of a Message Queuing receive function, such as the security information and to enable or disable the function.
  • Configure a Message Queuing receive function: Services tab
 To modify the server on which the Message Queuing receive function runs, the polling information, or the preprocessor that the Message Queuing receive function uses.
  • Add an HTTP receive function
 To create an HTTP receive function. You must follow this task with the Configure access privileges based on IIS protection level task for the receive transport to work properly.
  • Configure an HTTP receive function: General tab
 To disable or enable the HTTP receive function.
  • Configure an HTTP receive function: Services tab
 To modify the services configuration of the HTTP receive function, such as the server on which the HTTP receive function runs, the virtual directory used, where the HTTP receive function submits to, and whether a correlation token is used.
  • Configure advanced properties for File, Message Queuing, or HTTP receive functions
 To configure advanced properties for receive functions. These properties include openness level, envelope and channel name, and source and destination organization information. You can configure the advanced properties when creating the receive function, or whenever necessary.
  • Configure access privileges based on IIS protection level
 This task must be performed after an HTTP receive function has been created for the receive transport to work properly.
  • Delete a receive function
 To permanently delete a receive function.
Manage BizTalk Services:
  • Start a BizTalk service
 To start a BizTalk service on the associated server. Starting services enables the processing of messages by that server. The server must be in the stopped state before it can be started.
  • Stop a BizTalk service
 To stop BizTalk services on the associated server. Stopping services halts the processing of messages by that server. The server must be in the running state before it can be stopped. Stopping services is typically used to temporarily suspend processing while making changes to the configuration or when troubleshooting issues.
Manage Event Viewer:
  • Configure Event Viewer for BizTalk Server errors
 To show only the events for BizTalk Server and/or XLANG Scheduler in the application event log. This is typically done when there are a lot of non-BizTalk Server events that you do not want to see while troubleshooting.
  • View application-related errors in Event Viewer
 To look at error messages logged into Event Viewer.
Manage XLANG Applications and Databases:
  • Use stored procedures to delete records from the persistence database
 To delete old persistence documents from the persistence database.
  • Shut down all XLANG applications
 To perform a controlled shutdown for all XLANG schedules associated with all XLANG COM+ applications. Doing this saves the state for all running XLANG schedules to the persistence database.
  • Restart all XLANG applications
 To perform a controlled restart for all XLANG COM+ applications.
Manage the Default XLANG Scheduler Application:
  • Change the application identity for the default XLANG Scheduler application
 When BizTalk Server is initially installed, the XLANG Scheduler COM+ application is configured to run as the interactive user. Before the XLANG Scheduler engine can be used when no interactive user is logged on, the application must be configured to run as a specific Windows account.
Manage Other COM+ Applications That Host XLANG Schedules:
  • Create a new empty persistence database
 To create a new persistence database with the default settings.
  • Change the application identity for a COM+ application
 To change the default interactive user account for a COM+ application.
  • Change the DSN settings for a COM+ application
 To modify the data source name (DSN) settings for a COM+ application and to generate the structure for the new empty persistence database.
  • Shut down a COM+ application that hosts XLANG schedules
 To perform a controlled shutdown of all XLANG schedules associated with a specific COM+ XLANG application. Doing this saves the state for XLANG schedules to the persistence database.
  • Monitor Running XLANG Schedules
 This topic provides information about the tools available to monitor the health of the running XLANG schedules.


How to Perform BizTalk Server Administration Tasks

This section provides task-specific information about using BizTalk Server Administration. It is highly recommended that you review the About BizTalk Server Administration section to fully understand all the features and capabilities of BizTalk Server Administration.

The following procedures and topics are covered in this section:

  • Open BizTalk Server Administration

  • Open Component Services

  • Publish BizTalk Server 2002 in Active Directory

  • Delete BizTalk Server 2002 from Active Directory

  • Add users to the BizTalk Server Administrators group

  • Configure the BizTalk Messaging Management database

  • Change the BizTalk Messaging Management database being administered in a tools installation

  • Refresh the administration console

  • Add, Delete, and Configure a Server Group

  • Add, Delete, and Configure Servers in a Group

  • Manage Servers in a Group

  • Manage Queues

  • Manage Databases for a Server Group

  • Manage Receive Functions for a Server Group

  • Manage BizTalk Services

  • Manage Event Viewer

  • Manage XLANG Applications and Databases


Open BizTalk Server Administration

You will perform most of the BizTalk Server administrative tasks in the BizTalk Server Administration Microsoft Management Console (MMC) snap-in.

  • On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.


Open Component Services

Some of the administrative tasks require the use of Component Services.

  • On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.


Publish BizTalk Server 2002 in Active Directory

After you install BizTalk Server 2002, you can publish it in Microsoft® Active Directory™ to identify the availability of BizTalk Server in a distributed environment. For example, you might need to know which computers are running BizTalk Server. You can determine this by publishing BizTalk Server 2002 in Active Directory.

  1. On the Start menu, click Run.

  2. In the Open box, type cmd and click OK.

  3. At the command prompt, change the directory to the Setup folder in your BizTalk Server 2002 installation directory.

    For example: At the command prompt, type cd \Program Files\Microsoft BizTalk Server\Setup and press ENTER.

  4. At the command prompt, type cscript AD_registration.vbs and press ENTER.

  5. In the confirmation dialog box, click OK.

  6. At the command prompt, type exit and press ENTER.

Note

  • The AD_registration.vbs script is not designed to be used on a remote computer. It is recommended that you run this script on a local computer. If you must register a remote computer, you must make the following change:
    • Change the value of the ServerName variable in the AD_registration.vbs script to the name of the remote computer. When you do this, the local computer calls the Windows Management Instrumentation (WMI) provider on the remote computer to be registered. The WMI provider of the remote computer implements the appropriate code.


Delete BizTalk Server 2002 from Active Directory

When you remove BizTalk Server 2002 from a computer, its registration is not automatically removed from Active Directory. You need to remove the registration of that computer so that only those computers still running BizTalk Server 2002 are properly identified when you query Active Directory.

  1. On the Start menu, click Run.

  2. In the Open box, type cmd and click OK.

  3. At the command prompt, change the directory to the Setup folder in your BizTalk Server 2002 installation directory.

    For example: At the command prompt, type cd \Program Files\Microsoft BizTalk Server\Setup and press ENTER.

  4. At the command prompt, type cscript AD_registration.vbs /u and press ENTER.

  5. In the confirmation dialog box, click OK.

  6. At the command prompt, type exit and press ENTER.


Add users to the BizTalk Server Administrators group

To add users to the BizTalk Server Administrators group, you must be a member of the Windows 2000 local Administrators group. For more information about adding users to the Windows 2000 local Administrators group, see "Add a user to a group" in Windows 2000 Help.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

  2. Expand System Tools, expand Local Users and Groups, and then click the Groups folder.

    The folder contents appear in the details pane.

  3. In the details pane, click BizTalk Server Administrators.

  4. On the Action menu, point to All Tasks and click Add to Group.

    The BizTalk Server Administrators Properties dialog box appears.

  5. Click Add.

  6. In the Look in list, click your domain or computer name.

  7. In the list that contains the users and computers associated with the domain or computer you selected in step 6, click the user account to add, click Add, and then click OK.

  8. Click OK to close the BizTalk Server Administrators Properties dialog box.

Related Topic

Administration Privileges


Configure the BizTalk Messaging Management database

Perform this procedure if you need to take the BizTalk Messaging Management database offline for maintenance. For BizTalk Server to continue working without interruption while you perform this maintenance, you must replicate the BizTalk Messaging Management database and point all the servers to this replica.

Note

  • If you point your servers at another database that is not a replica of the original, it might be difficult to return to your original BizTalk Messaging Management database configuration once the maintenance is complete. This method is not recommended.

For more information about changing the database, see Changing the BizTalk Messaging Management database.

  1. Stop all servers in the Microsoft BizTalk Server 2002 node.

    For more information, see Stop a server in a group.

  2. In BizTalk Server Administration, click Microsoft BizTalk Server 2002.

  3. On the Action menu, click Properties.

    The Microsoft BizTalk Server 2002 Properties dialog box appears.

  4. On the General tab, you can change the following properties:
    • SQL database name. Type the name of the BizTalk Messaging Management database replica that you want all server groups to use while the original database is offline.

    • SQL Server name. Type the name of the server that stores the Microsoft® SQL Server™ database replica.
  5. Click OK.

  6. Shut down the BizTalk Server Interchange Application.

    For more information, see Shut down the BizTalk Server Interchange Application.

  7. Restart all servers in the Microsoft BizTalk Server 2002 node.

    For more information, see Start a server in a group.

  8. Restart the BizTalk Messaging Service.

    For more information, see Start a BizTalk service.

Notes

  • When you change the BizTalk Messaging Management database or point the server groups to a different Microsoft SQL Server, all BizTalk Server servers in the BizTalk Messaging Management database are updated with the new information.

  • The BizTalk Server Interchange Application will restart automatically the next time a message is submitted through the IInterchange COM+ interface.

  • Microsoft BizTalk Server 2002 depends on Microsoft Windows® integrated authentication for access to SQL Server. Therefore, BizTalk services must run under a domain or local account that has been granted access to SQL Server. In cases where the password for the BizTalk Server Messaging service account changes, it will be necessary to change the BizTalk Server Messaging service account password using the command line utility provided. For more information about changing the service account password, see Changing the Service Account Password.

Related Topics

Changing the BizTalk Messaging Management database

Manage BizTalk Services

Shut down the BizTalk Server Interchange Application

Start a server in a group

Stop a server in a group


Change the BizTalk Messaging Management database being administered in a tools installation

This procedure changes the BizTalk Messaging Management database being administered from a client computer with a tools installation of BizTalk Server. However, it does not change the BizTalk Messaging Management database that the BizTalk Server run time points to. To change the BizTalk Messaging Management database that the BizTalk Server run time points to, see Configure the BizTalk Messaging Management database.

  1. In BizTalk Server Administration, click Microsoft BizTalk Server 2002.

  2. On the Action menu, click Select Config DB.

    The Select Management Database dialog box appears.

  3. In the SQL database name box, type the name of the BizTalk Messaging Management database that you want to manage from the client computer.

  4. In the SQL Server name box, type the name of the server that stores the Microsoft SQL Server database on which the BizTalk Messaging Management database to be administered is stored.

  5. Click OK.

Note

  • This option is available only in a tools installation of BizTalk Server.

Related Topic

Administration Features of a BizTalk Server Tools Installation


Refresh the administration console

Because there is no automatic refresh cycle for the administration console, you must perform this procedure to view the current status of the following items:

  • Microsoft BizTalk Server 2002 node

  • Server groups

  • Servers

  • Queues

  • Receive functions
  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and expand the items in the console tree until you locate the item that you want to refresh.

  2. You might need to expand Server Groups, Queues, Receive Functions, and Servers to find the item you want to refresh.

  3. Click the item you want to refresh.

  4. On the Action menu, click Refresh.

Note

  • You can perform this procedure on any item in the console tree. When you refresh the administration console at the root, all items in the administration console are refreshed. When you refresh a server group, only the items in that group are refreshed.

Related Topics

Groups and Servers

Receive Functions

Using Queues


Add, Delete, and Configure a Server Group

Server groups are collections of individual servers that are centrally managed, configured, and monitored. Server groups are a key factor in the scalability of BizTalk Server. By creating additional server groups, you can increase throughput by partitioning processing across more computers. Servers in a BizTalk Server group have in common:

  • A Shared Queue database that persists all documents until they are successfully processed.

  • A Tracking database that is used to log document and interchange activity and to run reports.

  • Receive functions.

  • All components that the server requires when processing documents and interchanges, such as transport components and application integration components (AICs).

The following procedures are covered in this section:

  • Add a server group

  • Configure general properties for a server group

  • Configure connection properties for a server group

  • Configure tracking properties for a server group

  • Configure the parser order for a server group

  • Delete a server group

Note

  • If you are setting up multiple server groups for scalability and improved performance, use only one BizTalk Messaging Management database. Otherwise, these servers cannot share the same BizTalk Messaging Management configuration.


Add a server group

As your business needs change, you might want to restructure your BizTalk Server groups to optimize performance for your current needs. In doing so, you might need to add new server groups to better manage your organization.

  1. In BizTalk Server Administration, click Microsoft BizTalk Server 2002.

  2. On the Action menu, point to New and click Group.

    The New Group dialog box appears.

  3. In the Group name box, type the name of the new server group.

  4. In the Tracking database area:
    • In the Tracking database name box, type the name of the Tracking database for this server group.

    • In the Tracking SQL Server name box, type the name of the server on which the Tracking database for this server group is stored.
  5. In the Shared Queue database area:
    • In the Shared Queue database name box, type the name of the Shared Queue database for this server group.

    • In the Shared Queue SQL Server name box, type the name of the server on which the Shared Queue database for this server group is stored.
  6. Click OK.

Important

  • Do not use any of the following characters in the name of the server group:

    ~ ` ! @ # $ % ^ & * ( ) + = [ ] { } | ;\" '< > , . ?.

    For more information about invalid characters, see About Windows Management Instrumentation.

Notes

  • This procedure creates a server group. To configure the server group with additional settings, see Configure general properties for a server group.

  • If you are setting up multiple server groups for scalability and improved performance, use only one central BizTalk Messaging Management database. Otherwise, these servers cannot share the same BizTalk Messaging Management configuration.

  • Microsoft BizTalk Server 2002 depends on Microsoft Windows integrated authentication for access to SQL Server. Therefore, BizTalk services must run under a domain or local account that has been granted access to SQL Server. In cases where the password for the BizTalk Server Messaging service account changes, it will be necessary to change the BizTalk Server Messaging service account password using the command line utility provided. For more information about changing the service account password, see Changing the Service Account Password.

Related Topics

Add, Delete, and Configure Servers in a Group

Configure general properties for a server group

Groups and Servers

Managing the BizTalk Messaging Management Database

Shared Queue Database

Tracking Database

About Windows Management Instrumentation


Configure general properties for a server group

This procedure enables you to configure the general properties for a specific server group so that you can partition processing between different server groups.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group you want to configure.

  2. On the Action menu, click Properties.

    The BizTalk Server Group Properties dialog box appears.

  3. In the SMTP host box, type the SMTP host name that this server group uses.

    Important

    • The SMTP host field is optional. However, you must configure this field if you plan to use SMTP as a transport service in BizTalk Messaging Manager. For example, you cannot choose SMTP as primary or backup transport in BizTalk Messaging Manager unless you have the SMTP host configured here.
  4. In the Reliable messaging reply-to URL box, type the URL this server group uses to receive reliable messaging delivery receipts by using one of the following supported protocols: File, Message Queuing, HTTP, HTTPS, or SMTP.
    For the following transport | Use this prefix
    File | file://
    Message Queuing | queue://Direct=OS:<servername>\<queuename>
    Hypertext Transfer Protocol (HTTP) | http://
    Secure Hypertext Transfer Protocol (HTTPS) | https://
    Simple Mail Transfer Protocol (SMTP) | mailto:

    If you specify Message Queuing, you must use a format name. In addition, queue:// must precede the format name. For more information about format names, see Available Receive Functions.

  5. In the Messaging Management object cache refresh interval (seconds) list, click the number of seconds between cache updates for the server group.

    The range for this value is between 1 and 300 seconds. By default, the server updates this cache every 50 seconds.

  6. In the Proxy server area, select the Use a proxy server check box if you want to configure BizTalk Server to connect to the Internet through a proxy server.

    Enter the address, port, user name, and password for the proxy server that you want to use.

  7. Click OK.

  8. Perform the following steps only if you made any changes in the Proxy server area:
    • Stop each server in the group for which you configured the general properties. For more information about stopping a server, see Stop a server in a group.

    • Start each server in the group for which you configured the general properties. For more information about starting a server, see Start a server in a group.

Notes

  • Reliable messaging in BizTalk Server is BizTalk Framework 2.0-compliant. For more information about reliable messaging and BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/) and search for BizTalk Framework 2.0.

  • When you configure the Reliable messaging reply-to URL, use an Active Server Pages (ASP) page or message queue with a receive function monitoring it. If you do not want to configure your own ASP page initially, use the ReceiveStandard.asp file shipped with BizTalk Server. You can find this sample ASP page in \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReceiveScripts. This page is designed to take posts and submit them to BizTalk Server. For more information about implementing a secure site, go to the MSDN Online Library Web site (www.msdn.microsoft.com/library/default.asp) and search for the article "Implementing a Secure Site with ASP."

  • If you specify the URL to include localhost in the Reliable messaging reply-to URL box, the receive function will not work properly. Do not specify localhost in this field.

  • The response to an HTTP post is expected to be text. If the response requires binary data, encode the binary data using MIME or uuencode.

  • The return receipt for reliable messaging must be encoded using Unicode.

Related Topics

Administration Cache

Available Receive Functions

Start a server in a group

Stop a server in a group


Configure connection properties for a server group

This procedure enables you to change the Tracking and Shared Queue databases that the BizTalk Server group uses. Typically these databases need to be modified when changing to another database or server is required, such as part of disaster recovery or backing up an engine.

  1. Stop all servers on the BizTalk Server group that you want to configure.

    For more information, see Stop a server in a group.

  2. Shut down the BizTalk Server Interchange Application.

    For more information, see Shut down the BizTalk Server Interchange Application.

  3. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group that you want to configure.

  4. On the Action menu, click Properties.

    The BizTalk Server Group Properties dialog box appears.

  5. Click the Connection tab.

  6. In the Tracking database area:
    • In the Tracking database name box, type the name of the Tracking database that you want this server group to use.

    • In the Tracking SQL Server name box, type the name of the Microsoft SQL Server that stores the Tracking database that you want this server group to use.
  7. In the Shared Queue database area:
    • In the Shared Queue database name box, type the name of the Shared Queue database that you want this server group to use.

    • In the Shared Queue SQL Server name box, type the name of the Microsoft SQL Server that stores the Shared Queue database that you want this server group to use.
  8. Click OK.

  9. Restart all servers on the BizTalk Server group that you just configured.

    For more information, see Start a server in a group.

Notes

  • Microsoft BizTalk Server 2002 depends on Microsoft Windows integrated authentication for access to SQL Server. Therefore, BizTalk services must run under a domain or local account that has been granted access to SQL Server. In cases where the password for the BizTalk Server Messaging service account changes, it will be necessary to change the BizTalk Server Messaging service account password using the command line utility provided. For more information about changing the service account password, see Changing the Service Account Password.

  • If you change any values in the Tracking database area, you must update the connection string in the Connection.vbs file with the new Tracking database information. You can find Connection.vbs in the \Program Files\Microsoft BizTalk Server\BizTalkTracking\VBScripts folder. The Initial Catalog property in the connection string contains the name of the Tracking database. Update this property to update the Tracking database name. The connection string in the Connection.vbs file is:
    Const g_ConnectionString = "Provider=SQLOLEDB.1;
Persist Security Info=False;Integrated Security=SSPI;
Initial Catalog=<databasename>;
Data Source=<servername>;Connect Timeout=15"

    The Data Source property in the connection string contains the name of the SQL Server hosting the Tracking database. This property needs to be updated to reflect the correct SQL Server name for the Tracking database.

Related Topics

Available Receive Functions

Groups and Servers

Shut down the BizTalk Server Interchange Application

Start a server in a group

Stop a server in a group


Configure tracking properties for a server group

Tracking settings for a server group determine whether tracking of interchanges is enabled or disabled. When you install Microsoft BizTalk Server 2002, document tracking is automatically enabled, the Log incoming interchange and Log outgoing interchange options are selected, and the metadata for interchanges is tracked. By following this procedure you can customize the tracking properties.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group that you want to configure.

  2. On the Action menu, click Properties.

    The BizTalk Server Group Properties dialog box appears.

  3. Click the Tracking tab.

  4. Select the Enable document tracking check box and any of the following options that you want to use:
    • Select the Log incoming interchange check box to log incoming interchanges.

    • Select the Log outgoing interchange check box to log outgoing interchanges.

    • Select the Log the original MIME-encoded message check box to log MIME-encoded messages.
  5. Click OK.

Caution

  • You can disable document tracking by clearing the Enable document tracking check box. However, you will lose important BizTalk Server 2002 functionality if you do this. For more information about tracking, see Understanding Tracking Settings for a Server Group.

Note

  • If the Enable document tracking check box is not selected, the Log incoming interchange, Log outgoing interchange, and Log the original MIME-encoded message check boxes are unavailable.

Related Topics

Groups and Servers

Understanding Tracking Settings for a Server Group


Configure the parser order for a server group

When BizTalk Server receives a document, it attempts to parse the document in the order in the parser list. The parser list order can be modified to optimize throughput by placing the most used parser at the top of the parser list.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group for which you want to configure the parser order.

  2. On the Action menu, click Properties.

    The BizTalk Server Group Properties dialog box appears.

  3. Click the Parsers tab.

    The parsers are listed in the Arrange the server call sequence box in the following order:

    • BizTalk.ParserXML.1

    • BizTalk.ParserEdifact.1

    • BizTalk.ParserX12.1

    • BizTalk.ParserFFile.1
  4. In the Arrange the server call sequence box, click the parser that you want to move and click either the up or down button to move the selected parser higher or lower in the server call sequence.

  5. When the parsers are arranged in the order you want, click OK.

Notes

  • The Refresh button picks up new parsers registered in the local registry. If you want a new parser to appear in the Arrange the server call sequence box, you must click the Refresh button on the server on which the parser is registered.

  • The parser list cannot be refreshed from a remote server. When you register custom parsers, you can refresh the parser list only from the server where it is registered.

  • The Parser tab is not available in a tools-only installation of BizTalk Server.

Related Topic

Parsers


Delete a server group

As your business needs change, you might want to restructure the BizTalk Server groups to optimize performance for your current needs. In doing so, you might need to delete some server groups to relocate the servers in that group to other areas of your production system that require more resources.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and expand the server group that you want to delete.

  2. Click a server in the server group that you want to delete.

  3. On the Action menu, click Stop.

    Repeat steps 2 and 3 for each server in the group until you have stopped all servers in the group.

  4. Click the server group.

  5. On the Action menu, click Delete.

    The User Action Confirmation dialog box appears.

  6. Click Yes.

Notes

  • You cannot delete a server group that contains one or more running servers. To stop the servers and delete the server group, you must have Windows 2000 Administrator privileges for all the servers in the group.

  • The Tracking and Shared Queue databases associated with the server group remain in Microsoft SQL Server even after you delete the group. To remove the Tracking and Shared Queue databases, you must manually delete them. For more information about how to delete these databases, see Remove the Tracking and Shared Queue databases.

Related Topics

Groups and Servers

Remove the Tracking and Shared Queue databases

Stop a server in a group


Add, Delete, and Configure Servers in a Group

Servers in a server group are configured to balance server performance and maximum throughput. As your business needs change, you might want to restructure the BizTalk Server groups to optimize performance for your current needs. In doing so, you might need to add new servers to a group, move servers from one group to another, or adjust the server settings that were configured when BizTalk Server was installed. For example, you might be required to process more documents more quickly. Or you might need to configure a server in a group to receive only interchanges and documents.

It is highly recommended that you review BizTalk Servers in About BizTalk Server Administration to fully understand BizTalk Servers.

The following procedures are covered in this section:

  • Add a server to a group

  • Delete a server from a group

  • Configure a server in a group

  • Change the BizTalk Messaging Management database for a server

Note

  • When you adjust server properties, experiment with various combinations in a test environment before you change the server properties on your production BizTalk Servers.


Add a server to a group

This task enables you to add a BizTalk Server to an already configured BizTalk Server group. Each group can have a variable number of servers associated with it. Therefore, you can maximize the throughput by optimizing the number of servers in a group against the processing power of the servers that hold the databases.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group to which you want to add a server.

  2. On the Action menu, point to New and click Server.

    The Add a BizTalk Server dialog box appears.

  3. In the BizTalk Server name box, type the name of an existing server on which you have a complete installation of BizTalk Server 2002.

  4. Click OK.

Important

  • All servers within a group must have the same version and language of BizTalk Server installed. If there are servers with different versions of BizTalk Server (BizTalk Server 2000, BizTalk Server 2000 SP1, BizTalk Server 2002 Enterprise Edition, or a different language version of BizTalk Server) installed within a group, the databases will not function properly.

Notes

  • To view the global properties for the server group to which you added the server, right-click the group and click Properties.

  • The server to be added must have the same version of BizTalk Server installed as the group prior to it being added to the server group.

Related Topics

Groups and Servers

Manage Servers in a Group

Understanding Server Properties


Delete a server from a group

As your business needs change, you might want to restructure the BizTalk Server groups to optimize performance for your current needs. In doing so, you might need to delete servers from a server group to relocate the servers in that group to other areas of your production system that require more resources.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server that you want to delete, and then click the server.

  2. On the Action menu, click Stop.

    The server finishes processing all current interchanges and documents.

  3. On the Action menu, click Delete.

    The User Action Confirmation dialog box appears.

  4. Click Yes.

Note

  • You cannot delete a server from a server group if a receive function(s) points to it to process documents. You can edit the receive function(s) to point to other servers, or you can delete the receive function(s) if it no longer can be used.

Related Topics

Free interchanges from a server

Groups and Servers

Manage Receive Functions for a Server Group

Manage Servers in a Group


Configure a server in a group

This procedure enables you to configure the general properties for a specific server. Creating receive functions in servers that do not participate in work-item processing improves BizTalk Server throughput.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server that you want to configure, and then click the server.

  2. On the Action menu, click Stop.

    You cannot change server configuration settings while the server is running.

  3. On the Action menu, click Properties.

    The <computer name> Properties dialog box appears.

  4. In the Maximum number of receive function threads allowed box, type a number in the range from 1 through 128.

    The default value is 4. For more information about how to configure this option, see Understanding Server Properties.

  5. If you want the server to process items in the Work queue, click the Participate in work-item processing check box.

    When this check box is selected, the server processes documents in the Work queue. Clear this check box if you do not want the server to process documents in the Work queue. For more information about how to configure this option, see Understanding Server Properties.

  6. In the Maximum number of worker threads per processor allowed box, type a number in the range from 1 through 128.

    The default value is 4. For more information about how to configure this option, see Understanding Server Properties.

  7. In the Time between BizTalk Server Scheduler calls (milliseconds) box, type a number in the range from 1 through 4294967295.

    The default value is 2000. For more information about how to configure this option, see Understanding Server Properties.

  8. Click OK.

  9. Right-click the server you configured and click Start.

Note

  • If the Participate in work-item processing check box is not selected, the Maximum number of worker threads per processor allowed and Time between BizTalk Server Scheduler calls (milliseconds) check boxes are unavailable.

Related Topics

Groups and Servers

Manage Servers in a Group

Understanding Server Properties


Change the BizTalk Messaging Management database for a server

Changing the BizTalk Messaging Management database for a server is typically only necessary when a permanent change to another database is needed due to disaster recovery or when the server hosting the database is changed.

Important

  • Use this procedure to associate a server with a different BizTalk Messaging Management database. For more information about moving servers between BizTalk Messaging Management databases, see Moving Servers Between BizTalk Messaging Management Databases. For more information about changing the BizTalk Messaging Management database for server groups, see Changing the BizTalk Messaging Management Database.
  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server for which you want to change the BizTalk Messaging Management database, and then click the server.

  2. On the Action menu, click Stop.

  3. On the Action menu, click Delete.

    The User Action Confirmation dialog box appears.

  4. Click Yes.

  5. Close BizTalk Server Administration.

  6. On the Start menu, point to Programs, point to Accessories, and then click Windows Explorer.

  7. Browse to \Program Files\Microsoft BizTalk Server\Setup.

  8. Click BTSsetupDB.exe.

  9. On the File menu, click Open.

    The Microsoft BizTalk Server 2002 Database Setup Wizard opens.

  10. On the Welcome to the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard page, click Next.

  11. On the Configure a BizTalk Messaging Management Database page, click Create a new BizTalk Messaging Management database.

    —Or—

    Click Select an existing database.

  12. In the Server name box, click the name of the server where the new or existing BizTalk Messaging Management database is located.

  13. In the Database box, type the name of the new or existing BizTalk Messaging Management database.

  14. Click Next.

  15. On the Configure a BizTalk Server Group page, click Create a new BizTalk Server group.

    In the Group name box, type the name of the new group and click Next.

    —Or—

    Click Select an existing BizTalk Server group. In the Group name list, click the name of the existing group and click Next.

    You can select an existing BizTalk Server group only if you selected an existing database in step 11.

  16. If necessary, click Create a new Tracking database and click Next.

    —Or—

    Click Select an existing database. In the Server name list, click a server and click Next.

  17. If necessary, click Create a new Shared Queue database and click Next.

    —Or—

    Click Select an existing database. In the Server name list, click a server and click Next.

  18. On the Verify BizTalk Server Group page, verify the information you entered and click Next.

  19. On the Completing the Microsoft BizTalk Server 2002 Messaging Database Setup Wizard page, click Finish.

  20. Open BizTalk Server Administration.

  21. Expand Microsoft BizTalk Server 2002, expand the server group that contains the server for which you just changed the BizTalk Messaging Management database, and then click the server.

  22. On the Action menu, click Start.

    Related Topics

    Changing the BizTalk Messaging Management Database

    Managing BizTalk Server Databases

    Moving Servers Between BizTalk Messaging Management Databases


Manage Servers in a Group

This section provides task-specific information about how to manage servers in a BizTalk Server group. It is highly recommended that you review BizTalk Servers in About BizTalk Server Administration to fully understand BizTalk Servers.

The following procedures are covered in this section:

  • Start a server in a group

  • Stop a server in a group

  • Free interchanges from a server

  • Configure disk caching


Start a server in a group

Perform this procedure to start the BizTalk Server run-time services on the associated server so that it can participate in receiving and/or processing interchanges.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server that you want to start, and then click the server.

  2. On the Action menu, click Start.

Notes

  • Starting a server in a server group means starting the BizTalk Messaging Service on the server. After the BizTalk Messaging Service is running, the server can receive, transmit, process, and track documents that are queued to the Microsoft SQL Server databases.

  • The Start option is available only if the server is stopped. If the server is running, the command is unavailable.

Related Topics

Add, Delete, and Configure Servers in a Group

Administration Cache

Groups and Servers

Stop a server in a group


Stop a server in a group

Perform this procedure to stop the BizTalk Server run-time services on the associated server so that it will cease participation in receiving and/or processing interchanges.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server that you want to stop, and then click the server.

  2. On the Action menu, click Stop.

Notes

  • Stopping a server in a server group means stopping the BizTalk Messaging Service on the server. After the BizTalk Messaging Service is stopped, the server cannot receive, transmit, process, or track documents that are queued to the Microsoft SQL Server databases.

  • If you want to redistribute interchanges associated with a server that you have stopped, see Free interchanges from a server.

Related Topics

Add, Delete, and Configure Servers in a Group

Administration Cache

Free interchanges from a server

Groups and Servers


Free interchanges from a server

This procedure is used to free interchanges from a server so that the interchanges can be redistributed to other servers in the group if the original server is stopped or taken offline.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group that contains the server on which you want to free interchanges, and then click the server.

  2. On the Action menu, click Stop.

  3. On the Action menu, point to All Tasks and click Free Interchanges.

  4. On the Action menu, click Start.

Note

  • This task cannot be performed when the state of the server is either Running or AccessDenied.

Related Topics

Add, Delete, and Configure Servers in a Group

Groups and Servers

Stop a server in a group


Configure disk caching

Perform this procedure to enable or disable disk caching. When disk caching is disabled, loss of data is avoided during interruption of service failures such as power failures. However, it will degrade the performance of BizTalk Server.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

  2. In the Computer Management tree, expand Device Manager.

  3. On the right-hand side, double click Disk Drives.

  4. Right-click on the drive you want to configure disk caching, and click Properties.

    The <Device name> Disk Device Properties window appears.

  5. Click the Disk Properties tab.

  6. Clear the Write Cache Enabled check box.

Note

  • This procedure is a computer-wide change of the disk cache properties.

Related Topics

Add, Delete, and Configure Servers in a Group

Groups and Servers

Stop a server in a group


Manage Queues

This section provides task-specific information about how to manage queues in BizTalk Server. It is highly recommended that you review Using Queues to fully understand BizTalk Server queues.

The following procedures are covered in this section:

  • Move documents to the Suspended queue

  • View error descriptions

  • View interchanges

  • View documents

  • Resubmit documents

  • Delete documents


Move documents to the Suspended queue

Any item in the Work, Retry, or Scheduled queues can be moved to the Suspended queue. Move interchanges and documents to the Suspended queue only if you want to prevent them from being processed. Once an interchange or document is moved to the Suspended queue, it can be deleted, resubmitted, or retransmitted to the Work queue to complete processing.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the document that you want to move, and then expand Queues.

  2. Expand the queue that contains the document that you want to move and click the document.

  3. On the Action menu, point to All Tasks and click Move to Suspended Queue.

Related Topics

Suspended Queue

Using Queues


View error descriptions

This procedure enables you to evaluate what error caused a document to be placed in the Suspended queue.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the document that you want to view, expand Queues, and then click Suspended Queue.

  2. In the details pane, click the document that you want to view.

  3. On the Action menu, click View Error Description.

Related Topics

Suspended Queue

Using Queues

View documents

View interchanges


View interchanges

This task enables you to view the contents of an interchange that is placed in the Suspended queue due to parsing or transmission failures by opening a separate view window. This task is not valid for interchanges that failed due to agreement problems.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the interchange that you want to view, expand Queues, and then click Suspended Queue.

  2. In the details pane, click the interchange that you want to view.

  3. On the Action menu, click View Interchange.

    The Document Content dialog box appears.

Notes

  • If you try to view a large interchange, the data might be truncated. You can view up to 4 megabytes (MB) of data in the Document Content dialog box.

  • If BizTalk Server could not parse the interchange, you might see binary data in the Document Content dialog box. For more information about parser errors, see Parsing errors.

  • View Interchange is an available menu option for the following Suspended queue states:
    • Custom Component

    • Parsing

    • Encoding

    • Signing

    • Encrypting

    • Transmitting
  • View Interchange and View Document never appear on the Action menu at the same time.

  • View Interchange is not available in a tools-only installation of BizTalk Server.

Related Topics

An interchange or document appears as binary data in the Suspended queue

Suspended Queue

Using Queues

View documents

View error descriptions


View documents

This task enables you to view the contents of a document that is in the Suspended queue due to a trading partner agreement problem by opening a separate view window. This task is not valid for documents that failed due to parsing or transmission failures.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the document that you want to view, expand Queues, and then click Suspended Queue.

  2. In the details pane, click the document that you want to view.

  3. On the Action menu, click View Document.

    The Document Content dialog box appears.

Notes

  • If you try to view a large document, the data might be truncated. You can view up to 4 megabytes (MB) of data in the Document Content dialog box.

  • View Document is an available menu option for the following Suspended queue states:
    • Document Validation

    • Channel Selection

    • Mapping

    • Correlating

    • Serializing
  • View Document and View Interchange never appear on the Action menu at the same time.

  • View Document is not available in a tools-only installation of BizTalk Server.

Related Topics

An interchange or document appears as binary data in the Suspended queue

Suspended Queue

Using Queues

View error descriptions

View interchanges


Resubmit documents

This procedure enables you to resubmit to the Work queue a document that was placed in the Suspended queue. This is usually done after the cause of the transmission failure has been addressed.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the document that you want to resubmit, expand Queues, and then click Suspended Queue.

  2. In the details pane, click the document that you want to resubmit.

  3. On the Action menu, point to All Tasks and click Resubmit.

Notes

  • This procedure can also be used to retransmit documents.

  • Not all documents in the Suspended queue can be resubmitted. In some situations, you must delete the document and submit it again from the original application or organization. For more information about documents in the Suspended queue, see Suspended Queue.

Related Topics

Suspended Queue

Using Queues


Delete documents

This procedure enables you to delete a document from the Suspended queue. Usually this is done when the message is no longer needed, or when you have already saved the message.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the group that contains the document that you want to delete, expand Queues, and then click Suspended Queue.

  2. In the details pane, click the document that you want to delete.

  3. On the Action menu, click Delete.

    The User Action Confirmation dialog box appears.

  4. Click Yes.

Related Topics

Suspended Queue

Using Queues


Manage Databases for a Server Group

This section provides task-specific information about how to manage databases for a BizTalk Server group. It is highly recommended that you review Manage BizTalk Server Group Databases to fully understand BizTalk Server databases.

The following procedures are covered in this section:

  • Shut down the BizTalk Server Interchange Application

  • Remove the Tracking and Shared Queue databases

  • Manually restore the Tracking database

  • Manually restore the Shared Queue database


Shut down the BizTalk Server Interchange Application

The BizTalk Server Interchange Application hosts the roles that limit who can send interchanges and documents to BizTalk Server. This application needs to be shut down any time there is a change in the connection to the BizTalk Messaging Management, Tracking, or Shared Queue databases.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. Expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click BizTalk Server Interchange Application.

  4. On the Action menu, click Shut down.

Note

  • You can shut down the BizTalk Server Interchange Application from a remote server. If you do this, expand the <remote computer name> instead of My Computer in step 2.

Related Topics

Administration Cache

Configure connection properties for a server group

Configure tracking properties for a server group

Groups and Servers

Open Component Services

Tracking Database


Remove the Tracking and Shared Queue databases

The Tracking and Shared Queue databases are usually removed only after the BizTalk Server groups have been configured to use a different Tracking and/or Shared Queue database. If the Tracking and/or Shared Queue database is removed before you configure the BizTalk Server groups to use a different database, BizTalk Server will not function properly.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the individual server that contains the databases that you want to delete.

  3. Expand the Databases folder and click the database that you want to delete.

  4. On the Action menu, click Delete.

    The Delete Database dialog box appears.

  5. To save the backup and restore history for the database, clear the Delete backup and restore history for the database check box.

  6. Click Yes.

Note

  • The default name for the Tracking database is InterchangeDTA. The default name for the Shared Queue database is InterchangeSQ.

Related Topics

Groups and Servers

Shared Queue Database

Stop a server in a group

Tracking Database


Manually restore the Tracking database

Perform this procedure if the Tracking database has been corrupted or damaged. This procedure assumes that a backup has been previously created.

Caution

  • When you manually restore the Tracking database, you lose all data. If you need to keep this data, back up the data before you restore the Tracking database.
  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which you want to restore the database.

  3. Click Databases.

  4. On the Action menu, click New Database.

    The Database Properties dialog box appears.

  5. On the General tab, in the Name box, type a name for the Tracking database and click OK.

  6. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Query Analyzer.

    The Connect to SQL Server dialog box appears.

  7. In the SQL Server box, select the server where you want to restore the database.

  8. In the Connect using area, click the option corresponding to the authentication method you want to use to connect to SQL Server.

  9. Click OK.

  10. If you have Microsoft SQL Server 7.0 installed, in the Query window, in the DB list, click the name of the new Tracking database. Continue to step 14.

    —Or—

    If you have Microsoft SQL Server 2000 installed, in the Object Browser window, click the name of the new Tracking database.

  11. On the Query menu, click Change Database.

  12. On the Select Database of <server name> window, click the name of the new Tracking database.

  13. Click OK.

  14. Click the Load SQL Script Load SQL Script button button.

  15. Browse to \Program Files\Microsoft BizTalk Server\Setup.

  16. Click BTS_Tracking_Schema.sql and click Open.

  17. Click the Execute Query button.

  18. Click the Load SQL Script button.

  19. Verify that you are in the folder \Program Files\Microsoft BizTalk Server\Setup.

  20. Click BTS_Reporting.sql and click Open.

  21. Click the Execute Query button.

  22. Click the Load SQL Script button.

  23. Verify that you are in the folder \Program Files\Microsoft BizTalk Server\Setup.

  24. Click BTS_Tracking_Logic.sql and click Open.

  25. Click the Execute Query button.

  26. Click the Load SQL Script button.

  27. Verify that you are in the folder \Program Files\Microsoft BizTalk Server\Setup.

  28. Click BTS_WorkflowEvents_Logic.sql and click Open.

  29. Click the Execute Query button.

  30. Click the Load SQL Script button.

  31. Verify that you are in the folder \Program Files\Microsoft BizTalk Server\Setup.

  32. Click BTS_WorkflowEvents_Schema.sql and click Open.

  33. Click the Execute Query button.

  34. Close SQL Query Analyzer and SQL Server Enterprise Manager.

Related Topic

Manually restore the Shared Queue database


Manually restore the Shared Queue database

Perform this procedure if the Shared Queue database has been corrupted or damaged. This procedure assumes that a backup has been previously created.

Caution

  • When you manually restore the Shared Queue database, you lose all data. If you need to keep this data, back up the data before you restore the Shared Queue database.
  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which you want to restore the database.

  3. Click Databases.

  4. On the Action menu, click New Database.

    The Database Properties dialog box appears.

  5. On the General tab, in the Name box, type a name for the Shared Queue database and click OK.

  6. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Query Analyzer.

    The Connect to SQL Server dialog box appears.

  7. In the SQL Server box, select the server where you want to restore the database.

  8. In the Connect using area, click the option corresponding to the authentication method you want to use to connect to SQL Server.

  9. Click OK.

  10. If you have Microsoft SQL Server 7.0 installed, in the Query window, in the DB list, click the name of the new Shared Queue database. Continue to step 14.

    —Or—

    If you have Microsoft SQL Server 2000 installed, in the Object Browser window, click the name of the new Shared Queue database.

  11. On the Query menu, click Change Database.

  12. On the Select Database of <server name> window, click the name of the new Shared Queue database.

  13. Click OK.

  14. Click the Load SQL Script Load SQL Script button button.

  15. Browse to \Program Files\Microsoft BizTalk Server\Setup.

  16. Click BTS_Core_Schema.sql and click Open.

  17. Click the Execute Query button.

  18. Click the Load SQL Script button.

  19. Verify that you are in the folder \Program Files\Microsoft BizTalk Server\Setup.

  20. Click BTS_Core_Logic.sql and click Open.

  21. Click the Execute Query button.

  22. Close SQL Query Analyzer and SQL Server Enterprise Manager.

Related Topic

Manually restore the Tracking database


Manage Receive Functions for a Server Group

Receive functions are those functions that are set up on a BizTalk Server group to handle incoming interchanges with a specific protocol. These functions ultimately call the Receive methods on the inbound router object.

The following procedures are covered in this section:

  • Add a File receive function

  • Configure a File receive function: General tab

  • Configure a File receive function: Services tab

  • Add a Message Queuing receive function

  • Configure a Message Queuing receive function: General tab

  • Configure a Message Queuing receive function: Services tab

  • Add an HTTP receive function

  • Configure an HTTP receive function: General tab

  • Configure an HTTP receive function: Services tab

  • Configure advanced properties for File, Message Queuing, or HTTP receive functions

  • Configure access privileges based on IIS protection level

  • Delete a receive function

Note

  • If you replicate a receive function that is configured to use a user name and password, the receive function will be disabled due to an invalid password. To resolve this issue, you need to open the property page for each receive function, re-enter the password, and then enable the receive function.


Add a File receive function

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and expand the server group to which you want to add the File receive function.

  2. Click Receive Functions.

  3. On the Action menu, point to New and click File Receive Function.

    The Add a File Receive Function dialog box appears.

  4. In the Name box, type the name of the File receive function.

  5. In the Comment box, add a brief description (optional).

  6. In the Server on which the receive function will run list, click the name of a server in the group.

  7. In the File types to poll for box, type the extension of the files that BizTalk Server receives.

    The file type extension must be written in the following syntax:

    *.ext

    For example: *.xml

  8. In the Polling location box, type either the logical path or the universal naming convention (UNC) path to the directory this receive function uses as the file receiving location.

  9. In the Preprocessor list, click the name of the custom preprocessor.

    Leave this blank if you are not using a custom preprocessor.

  10. In the User name and Password boxes, type a valid user name and password to connect to the file receive location (optional).

    This is required only when the receive location is protected and a valid user name and password are required to connect to the server.

  11. To customize the receive function for non-self-routing documents, or to specify openness or pass-through options, click Advanced.

    For more information about advanced options, see Configure advanced properties for File, Message Queuing, or HTTP receive functions.

Notes

  • This procedure creates a File receive function with the default settings. To configure the File receive function with additional settings, see Configure a File receive function: General tab.

  • If you want to poll for more than one file type, use any standard wildcard format.

    For example: *.* or *.x?l

  • If you configure one or more File receive functions to monitor the same directory, use three-letter file extensions. If you use file extensions of more than three letters, verify that the first three letters are unique.

    For example: *.xml, *.1xml, *.12xml

  • File receive functions cannot process read-only files.

  • Verify that each receive function that you create has a unique name. You cannot assign identical names to receive functions.

  • If you replicate a receive function that is configured to use a user name and password, the receive function will be disabled due to an invalid password. To resolve this issue, you need to open the property page for each receive function, re-enter the password, and then enable the receive function.

Related Topics

Available Receive Functions

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure a File receive function: General tab

Configure a File receive function: Services tab

Custom Preprocessors

Receive Functions


Configure a File receive function: General tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure a File receive function, and then expand Receive Functions.

  2. Click the File receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. In the Comment box, add a brief description (optional).

  5. In the Security area, in the User name and Password boxes, type a valid user name and password to connect to this receive function.

    This is required only when the receive location is protected and a valid user name and password are required to connect to the server.

  6. If you do not want to shut down the functionality of this receive function, clear the Disable receive function check box and click Yes to confirm your choice.

Notes

  • File receive functions cannot process read-only files.

  • If you replicate a receive function that is configured to use a user name and password, the receive function will be disabled due to an invalid password. To resolve this issue, you need to open the property page for each receive function, re-enter the password, and then enable the receive function.

Related Topics

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure a File receive function: Services tab


Configure a File receive function: Services tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure a File receive function, and then expand Receive Functions.

  2. Click the File receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. Click the Services tab.

  5. In the Server on which the receive function will run list, click the server name.

  6. In the Polling location box, type either the logical path or the universal naming convention (UNC) path to the directory this receive function uses as the file receive location.

  7. In the File types to poll for box, type the extension of the files that BizTalk Server receives.

    The file type extension must be written in the following syntax:

    *.ext

    For example: *.doc

  8. In the Preprocessor list, click the name of the custom preprocessor.

    Leave this blank if you are not using a custom preprocessor.

  9. Click OK.

Notes

  • If you want to receive multiple file types, use any standard wildcard format.

    For example: *.*

  • If you configure one or more File receive functions to monitor the same directory, use three-letter file extensions. If you use file extensions of more than three letters, verify that the first three letters are unique.

    For example: *.xml, *.1xml, *.12xml

  • File receive functions cannot process read-only files.

Related Topics

Available Receive Functions

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Custom Preprocessors


Add a Message Queuing receive function

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and expand the server group for which you want to add a Message Queuing receive function.

  2. Click Receive Functions.

  3. On the Action menu, point to New and click Message Queuing Receive Function.

    The Add a Message Queuing Receive Function dialog box appears.

  4. In the Name box, type the name of the Message Queuing receive function.

  5. In the Comment box, add a brief description (optional).

  6. In the Server on which the receive function will run list, click the name of a server in the group.

  7. In the Polling location box, type the server and Message Queuing names that this receive function uses as the receive location.

    For example:

    Direct=OS:<servername>\<queuename>

    Select the processing server on which the queue resides. Transactional messaging is supported only by local queues.

  8. In the Preprocessor list, click the custom preprocessor.

    Leave this blank if you are not using a custom preprocessor.

  9. In the User name and Password boxes, type a valid user name and password to connect to Message Queuing.

    This is required only when the receive location is not on the server processing interchanges and documents.

  10. To customize the receive function for non-self-routing documents, or to specify openness or pass-through options, click Advanced.

    For more information about advanced options, see Configure advanced properties for File, Message Queuing, or HTTP receive functions.

Important

  • Do not prefix the <servername>\<queuename> with queue:// in the Polling location box. This is different from the general properties for a server group for which you use queue://. For more information about Message Queuing syntax, see Available Receive Functions. For more information about properties for a server group, see Configure general properties for a server group.

Notes

  • The Message Queuing receive function is not configured to accept pass-through submissions.

  • Verify that each receive function that you create has a unique name. You cannot assign identical names to receive functions.

  • A Message Queuing receive function will not work unless the user name and password supplied to the server on which BizTalk Server is running has read permission on the queue.

  • To ensure reliability, you must use transactional queues. If you use nontransactional queues, messages might be lost. For more information about transactional queues, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on the keywords "Message Queuing."

  • If you replicate a receive function that is configured to use a user name and password, the receive function will be disabled due to an invalid password. To resolve this issue, you need to open the property page for each receive function, re-enter the password, and then enable the receive function.

  • For more information about custom preprocessing, see Custom Preprocessors.

Related Topics

Available Receive Functions

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure a Message Queuing receive function: General tab

Custom Preprocessors

Receive Functions


Configure a Message Queuing receive function: General tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure a Message Queuing receive function, and then expand Receive Functions.

  2. Click the Message Queuing receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. In the Comment box, add a brief description (optional).

  5. In the Security area, in the User name and Password boxes, type a valid user name and password to connect to the message queue.

    This is required only when the receive location is not on the processing server.

  6. If you want to temporarily shut down the functionality of this receive function, select the Disable receive function check box and click Yes to confirm your choice.

Note

  • If you replicate a receive function that is configured to use a user name and password, the receive function will be disabled due to an invalid password. To resolve this issue, you need to open the property page for each receive function, re-enter the password, and then enable the receive function.

Related Topics

Configure a Message Queuing receive function: Services tab

Receive Functions


Configure a Message Queuing receive function: Services tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure a Message Queuing receive function, and then expand Receive Functions.

  2. Click the Message Queuing receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. Click the Services tab.

  5. In the Server on which the receive function will run list, click the server name.

  6. In the Polling location box, type the server and Message Queuing names that this receive function uses as the receive location.

    For example:

    Direct=OS:<servername>\<queuename>

  7. In the Preprocessor list, click the custom preprocessor.

    Leave this option blank if you are not using a custom preprocessor.

  8. Click OK.

Important

  • Do not prefix the <servername>\<queuename> with queue:// in the Polling location box. This is different from the general properties for a server group for which you use queue://. For more information about Message Queuing syntax, see Available Receive Functions. For more information about server group properties, see Configure general properties for a server group.

Note

  • For more information about custom preprocessing, see Custom Preprocessors.

Related Topics

Available Receive Functions

Configure general properties for a server group

Custom Preprocessors


Add an HTTP receive function

This procedure creates an HTTP receive function with the default settings. To configure the HTTP receive function with additional settings, see Configure advanced properties for File, Message Queuing, or HTTP receive functions.

Before you can perform this procedure, verify that Internet Information Services (IIS) is running on the server on which the HTTP receive function will run. Also, an IIS virtual directory with execute permissions must be used for the HTTP receive function to work properly. For more information about creating an IIS virtual directory, see the IIS 5.0 documentation.

For the HTTP receive function to work properly, when the client specifies the virtual directory where the data should be posted over Hypertext Transfer Protocol (HTTP) to the HTTP receive function, it is necessary that the query string is a multibyte character string (MBCS) encoded using the UTF-8 codepage. It is also important to note that if the Content-Type header is not set in an incoming request, then the HTTP receive function will default to USASCII. In this case, the instance data will be corrupted if it has double-byte character set (DBCS) characters embedded. For more information, go to the MSDN Online Library Web site (msdn.microsoft.com) and search on "Support for Multibyte Character Sets" and "Encoding.UTF8 Property."

  1. In Windows Explorer, browse to \Program Files\Microsoft BizTalk Server\HTTP Receive\BizTalkHTTPReceive.dll on your installation drive.

  2. Copy BizTalkHTTPReceive.dll to the directory the IIS virtual directory points to.

  3. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and expand the server group to which you want to add the HTTP receive function.

  4. Click Receive Functions.

  5. On the Action menu, point to New and click HTTP Receive Function.

    The Add an HTTP Receive Function dialog box appears.

  6. In the Name box, type the name of the HTTP receive function.

  7. In the Comment box, add a brief description (optional).

  8. In the Server on which the receive function will run box, select the server you want from the drop-down list.

  9. In the Virtual directory box, type the name of the virtual directory where the documents received by the HTTP receive function will be posted. The virtual directory typically includes the name of the HTTP receive function DLL and an optional query string.

    Examples of virtual directory names are:

    /<virtual directory>/BizTalkHTTPReceive.dll

    /<virtual directory>/BizTalkHTTPReceive.dll?Purchase%20Order

    Notes

    • Do not specify the server name in the Virtual directory box. The server has already been specified in the Server on which the receive function will run box.

    • If the virtual directory is configured with the name of the HTTP receive function DLL as one of the default documents, you need to include the dynamic-link library (DLL) as part of the virtual directory name.

    • The value entered in the Virtual directory box must omit the string http://.

    • You must use query strings to create multiple receive functions that use the same virtual directory.

    • The query string used in the Virtual directory box must use the URLEncode method to encode the query string. To include spaces, you must use the %20 string.
  10. In the Submit to box, select where (BizTalk/File) and how (Synchronously/Asynchronously) the HTTP receive function submits the document.

    If you choose BizTalk-Synchronously and you expect a return document, enter the return content type in the Return content type box. The value in the Return content type box should be consistent with the HTTP Content-Type established in the HTTP Specifications. For more information about the HTTP Specifications, go to the W3C Web site (www.w3.org).

    —Or—

    If you choose File, enter the path and file name to which the received document is to be written in the File path and name box. You can specify variables to be replaced at run time in the file name. The three variables supported are: %guid%, %server%, and %datetime%. For example, you can specify the file name and path as D:\Directory\File name%guid%.xml.

    Important

    • When a failure occurs while the HTTP receive function submits to a file, the message will not be stored in the Suspended queue.
  11. Select the Return correlation token check box if you want a correlation token to be returned to the sender of the document.

    When the document is submitted to BizTalk Server, the correlation token contains the submission GUID. When the document is submitted to a file, the correlation token contains the file name. For example, the correlation token can be:

    <BizTalkHttpReceive><CorrelationToken TokenType= SUBMIT>{1a3e5678-a2c9-12d4-a8cd-12a456e89012}</CorrelationToken></BizTalkHttpReceive>

  12. In the Preprocessor list, click the name of the custom preprocessor.

    Note

    • Leave this blank if you are not using a custom preprocessor.

    For more information, see Preprocessing Documents in a Receive Function.

  13. To customize the receive function for non-self-routing documents, or to specify openness or pass-through options, click Advanced.

    For more information about advanced options, see Configure advanced properties for File, Message Queuing, or HTTP receive functions.

For the HTTP receive function you just created to work, it is important to have the correct access privileges in the COM+ packages affected by different protection levels in Internet Information Services (IIS).

Continue to Configure access privileges based on IIS protection level.

Notes

  • Verify that each receive function that you create has a unique virtual directory name, including the query string. You cannot assign identical names to receive functions.

  • Multiple dynamic-link libraries (DLL) corresponding to different virtual directories may be deployed on the same server. Also, multiple directories can point to the same DLL. However, to improve performance, it is recommended you use only one DLL.

  • A client posts to the HTTP receive function using the URL /VirtualDirectory. However, when using IIS 5.0 and Windows 2000 Service Pack 2 (SP2), the DLL must also be part of the specified URL: /VirtualDirectory/BizTalkHTTPreceive.dll.

  • Once the HTTP receive function has been created, the basic submission type (BizTalk/File) cannot be modified.

  • When you select BizTalk-Synchronously for the Submit to box, and Return correlation token is also selected, a correlation token will be sent only when the return document is empty.

  • The correlation token is independent from the Orchestration correlation. For further information, see Correlation Token.

  • If the HTTP receive function submits synchronously, and the channel sends the message through a Message Queuing port, you might receive the following error, "Invalid usage of transaction." This occurs because the HTTP receive function is non-transactional but Message Queuing is transactional. To avoid this error, you must select the Single Message transactional level option for the channel. For more information about channel advanced properties, see Override messaging port defaults.

Related Topics

Available Receive Functions

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Configure an HTTP receive function: General tab

Configure an HTTP receive function: Services tab

Custom Preprocessors

Receive Functions


Configure an HTTP receive function: General tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure an HTTP receive function, and then expand Receive Functions.

  2. Click the HTTP receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. On the General tab, in the Comment box, add a brief description (optional).

  5. If you want to temporarily shut down the functionality of this receive function, select the Disable receive function check box and click Yes to confirm your choice.

Related Topics

Configure an HTTP receive function: Services tab

Configure advanced properties for File, Message Queuing, or HTTP receive functions


Configure an HTTP receive function: Services tab

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure an HTTP receive function, and then expand Receive Functions.

  2. Click the HTTP receive function that you want to configure.

  3. On the Action menu, click Properties.

    The Properties dialog box appears.

  4. Click the Services tab.

  5. In the Server on which the receive function will run box, click the server name.

  6. In the Virtual directory box, type the name of the virtual directory where the documents received by the HTTP receive function will be posted.

    Examples of virtual directory names are:

    /<virtual directory>/BizTalkHTTPReceive.dll

    /<virtual directory>/BizTalkHTTPReceive.dll?Purchase%20Order

    Notes

    • Do not specify the server name in the Virtual directory box. The server has already been specified in the Server on which the receive function will run box.

    • If the virtual directory is configured with the name of the HTTP receive function DLL as one of the default documents, you need to include the dynamic-link library (DLL) as part of the virtual directory name.

    • The value entered in the Virtual directory box must omit the string http://.

    • You must use query strings to create multiple receive functions that use the same virtual directory.

    • The query string used in the Virtual directory box must use the URLEncode method to encode the query string. To include spaces, you must use the %20 string.
  7. If the HTTP receive function submits to BizTalk Server, choose the method of submission (Asynchronously or Synchronously) in the Submit to box.

    If you choose BizTalk-Synchronously, enter the return content type in the Return content type box. The value in the Return content type box should be consistent with the HTTP Content-Type established in the HTTP Specifications. For more information about the HTTP Specifications, go to the W3C Web site (www.w3.org).

    International Issue

    • If the Content-Type header is not set in an incoming request, then the HTTP receive function will default to USASCII. In this case, the instance data will be corrupted if it has double-byte character set (DBCS) characters embedded.
  8. In the Preprocessor list, click the name of the custom preprocessor.

    Note

    • Leave this blank if you are not using a custom preprocessor.

    For more information, see Preprocessing Documents in a Receive Function.

  9. If the HTTP receive function submits to a File, enter the path and file name to which the received document is to be written in the File path and name box. You can specify variables to be replaced at run time in the file name. The three variables supported are: %guid%, %server%, and %datetime%. For example, you can specify the file name and path as D:\Directory\File name%guid%.xml.

  10. Select the Return correlation token check box if you want a correlation token to be returned to the sender of the document.

    When the document is submitted to BizTalk Server, the correlation token contains the submission GUID. When the document is submitted to a file, the correlation token contains the file name. For example, the correlation token can be:

    <BizTalkHttpReceive><CorrelationToken TokenType= SUBMIT>{1a3e5678-a2c9-12d4-a8cd-12a456e89012}</CorrelationToken></BizTalkHttpReceive>

  11. Click OK.

Notes

  • In a tools-only installation of BizTalk Server, the Administration console does not support the creation of an HTTP receive function.

  • The correlation token is independent from the Orchestration correlation. For further information, see Correlation Token.

  • Once the HTTP receive function has been created, the basic submission type (BizTalk/File) cannot be modified.

  • When you select BizTalk-Synchronously for the Submit to box, and Return correlation token is also selected, a correlation token will be sent only when the return document is empty.

  • A client posts to the HTTP receive function using the URL /VirtualDirectory. However, when using IIS 5.0 and Windows 2000 Service Pack 2 (SP2), the DLL must also be part of URL specified: /VirtualDirectory/BizTalkHTTPreceive.dll.

  • You must use query strings to create multiple receive functions that use the same virtual directory.

Related Topics

Available Receive Functions

Configure advanced properties for File, Message Queuing, or HTTP receive functions

Custom Preprocessors


Configure advanced properties for File, Message Queuing, or HTTP receive functions

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group for which you want to configure a receive function, expand Receive Functions, and then click the receive function that you want to configure.

  2. On the Action menu, click Properties.

    The Properties dialog box appears.

  3. Click the Advanced tab.

  4. In the Openness list, you can select:
    • Not open. Click this option when the source and destination are both explicitly declared in the receive function or in the document instance, and BizTalk Server does not have to parse the document for this information.

    • Open Destination. Click this option when the destination information is not explicitly declared in the messaging port. The destination is dynamically specified in the document instance or a submission parameter.

    • Open Source. Click this option when the source information is not explicitly declared in the channel. The source is dynamically specified in the document instance or a submission parameter.
  5. If you want to bypass all processing, such as decoding, decryption, signature verification, parsing, and so on, and only transport an interchange, select the Submit with a pass-through flag check box.

    You must select a channel if you select the Submit with a pass-through flag check box.

  6. In the Envelope name list, click the name of an envelope definition.

    Choose an envelope if you plan to receive flat files. Otherwise, leave this blank.

  7. In the Channel name list, click the name of a channel.

  8. In the Document definition name list, click the name of a document definition.

  9. In the Source and destination area, in the Source selected area, click Browse.

    The Select Source dialog box appears.

  10. In the Organization qualifier list, click the type of source organization qualifier.

  11. In the Organization identifier value list, click the source-organization identifier value and click OK.

  12. In the Source and destination area, in the Destination selected area, click Browse.

    The Select Destination dialog box appears.

  13. In the Organization qualifier list, click the type of destination organization qualifier.

    If you send documents to a distribution list, in the Organization qualifier list, you must choose GROUP.

  14. In the Organization identifier value list, click the destination-organization identifier value and click OK.

  15. Click OK.

Important

  • Before you can assign any of the objects in the following list as advanced properties of a receive function, you must create them. These objects are either created in BizTalk Messaging Manager or they are created programmatically and stored in the BizTalk Messaging Management database:
    • Envelopes

    • Channels

    • Document definitions

    • Source qualifiers

    • Source-organization identifier values

    • Destination qualifiers

    • Destination-organization identifier values

Notes

  • If you click Open Source or Open Destination in the Openness list, the Submit with a pass-through flag check box is unavailable.

  • If the Submit with a pass-through flag check box is selected, only the Channel list is available.

  • If you want to send a document to a distribution list, you must select GROUP in the Organization qualifier list in the Select Destination dialog box.

  • All the advanced receive-function properties are optional and can be left blank. For more information about submitting documents, see Routing or Understanding Receive Functions and Document Routing.

  • A pass-through submission bypasses the parsing, decryption, and decoding functions of BizTalk Server 2002. For more information about submitting documents with the pass-through flag set, see Understanding Receive Function Advanced Properties. For more information about submitting, see Submitting.

  • The Advanced tab is unavailable for an HTTP receive function that submits to a file.

  • The Advanced tab for the receive functions is unavailable in a tools-only installation of BizTalk Server.

Related Topics

Receive Functions

Routing

Submitting

Understanding Receive Function Advanced Properties

Understanding Receive Functions and Document Routing


Configure access privileges based on IIS protection level

After you add an HTTP receive function, it is important that certain COM+ packages are configured based on the level of isolation the virtual directory has:

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

  2. In the Computer Management tree, expand Services and Applications, expand Internet Information Services, and expand the name of the Web site that has the virtual directory used by the HTTP receive function (the default is Default Web Site).

  3. Right-click the name of the virtual directory and select Properties.

  4. On the Virtual Directory tab, note the level of Application Protection.

    If the application protection level is Low (IIS Process), go to step 5.

    If the application protection level is Medium (Pooled), go to step 7.

    If the application protection level is High (Isolated), go to step 9.

  5. If the application protection level is configured as Low (IIS Process), open Component Services, double-click Services, right-click World Wide Web Publishing Service, and select Properties.

  6. On the Log on tab, configure the Log on as property with the user that has security credentials to access the BizTalk Messaging Management database and the COM+ packages BizTalk Server Interchange Application and BizTalk Server Internal Utility.

  7. If the application protection level of the virtual directory is configured as Medium (Pooled), open Component Services, expand COM+ Applications, right-click IIS Out-of-Process Pooled Applications, and select Properties.

  8. On the Identity tab, configure the Account properties with the user that has security credentials to access the BizTalk Messaging Management database and the COM+ packages BizTalk Server Interchange Application and BizTalk Server Internal Utility.

  9. If the application protection level of the virtual directory is configured as High (Isolated), open Component Services, expand COM+ Applications, right-click IIS_{Default Web Site//root/virtual directory name}, and select Properties.

  10. On the Identity tab, configure the Account properties with the user that has security credentials to access the BizTalk Messaging Management database and the COM+ packages BizTalk Server Interchange Application and BizTalk Server Internal Utility.

Related Topic

Add an HTTP receive function


Delete a receive function

This task enables you to delete an instance of a receive function. This actually just removes the administrative object instance from the administrative database. It does nothing to or with the actual components and scripts related to this instance.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand the server group in which you want to delete a receive function, and then expand Receive Functions.

  2. Click the receive function that you want to delete.

  3. On the Action menu, click Delete.

    The User Action Confirmation dialog box appears.

  4. Click Yes.

Related Topic

Receive Functions


Manage BizTalk Services

When you make a fundamental change to your BizTalk Server configuration, such as changing the name of a database, or adding a Web server or firewall, a running service might still be using the parameters that apply to the old configuration. To synchronize all of the services for your new configuration, it is important to stop and restart the BizTalk services that are affected by the change.

The following procedures are covered in this section:

  • Start a BizTalk service

  • Stop a BizTalk service


Start a BizTalk service

This task enables you to start the BizTalk services associated with a specific server.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand BizTalk Server Group, and select the server on which you want to start the BizTalk Services.

  2. On the Action menu, click Start.

Related Topics

Stop a BizTalk service

Start a server in a group

Stop a server in a group


Stop a BizTalk service

This task enables you to stop the BizTalk services associated with a specific server. BizTalk services are usually stopped to temporarily suspend processing while making changes to the configuration database or when troubleshooting.

  1. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, expand BizTalk Server Group, and select the server on which you want to start the BizTalk Services.

  2. On the Action menu, click Stop.

Related Topics

Start a BizTalk service

Start a server in a group

Stop a server in a group


Manage Event Viewer

You can use the Event Viewer included in BizTalk Server Administration to help you troubleshoot server and document processing problems. The Event Viewer appears in the console tree of BizTalk Server Administration. All application-related errors for BizTalk Server 2002 are labeled BizTalk Server errors. All XLANG schedule–related errors are labeled XLANG Scheduler errors.

The following procedures are covered in this section:

  • Configure Event Viewer for BizTalk Server errors

  • View application-related errors in Event Viewer

Note

  • Some errors returned by Microsoft XML (MSXML) Parser within a custom script function might not be displayed in the Event Viewer. Errors associated with a document in the Suspended queue may not reflect the error returned in the script.


Configure Event Viewer for BizTalk Server errors

This task enables you to configure Event Viewer to show only the events for BizTalk Server and/or XLANG Scheduler. This is usually done when there are a lot of errors from other programs that you do not want to see while troubleshooting.

  1. In BizTalk Server Administration, expand Event Viewer.

  2. Click Application.

  3. On the Action menu, click Properties.

    The Application Properties dialog box appears.

  4. Click the Filter tab.

  5. In the Event source list, click one of the following:
    • BizTalk Server. This option filters the event sources for error messages that are related to BizTalk Messaging Services.

    • XLANG Scheduler. This option filters the event sources for error messages that are related to BizTalk Orchestration Services.
  6. Click OK to close the Application Properties dialog box.


View application-related errors in Event Viewer

  1. In BizTalk Server Administration, expand Event Viewer.

  2. Click Application.

    Application error messages are listed in the details pane.

  3. Click a message in the details pane.

  4. On the Action menu, click Properties.

Note

  • This procedure assumes you configured Event Viewer to display only BizTalk Server and XLANG Scheduler errors. For more information about how to display BizTalk Server and XLANG Scheduler errors, see Configure Event Viewer for BizTalk Server errors.


Manage XLANG Applications and Databases

This section provides information about how to manage the default XLANG Scheduler application created when you install BizTalk Server 2002. It also includes information about creating new COM+ applications to host XLANG schedule instances and new persistence databases to store XLANG schedule state information.

The following topics and procedures are covered in this section:

  • Use stored procedures to delete records from the persistence database

  • Shut down all XLANG applications

  • Restart all XLANG applications

  • Manage the Default XLANG Scheduler Application

  • Manage Other COM+ Applications That Host XLANG Schedules

  • Monitor Running XLANG Schedules

Caution

  • BizTalk Server 2002 provides a COM+ application called the XLANG Persistence Helper, which is used by all COM+ applications that host XLANG schedule instances. You should not change the configuration of the XLANG Persistence Helper in any way after setup completes.

Notes

  • For more information about Microsoft SQL Server, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Running XLANG Schedules

Run XLANG Schedules


Use stored procedures to delete records from the persistence database

The persistence database contains all the persistence information for the XLANG schedules that are running and that have run to completion. Because the data for the completed XLANG schedules is not deleted from the database, this database will continue to grow. You can use the following stored procedures to delete records from the persistence database.

sp_CleanDoneInstances @CompletedBefore='<GMT date and time>'

The sp_CleanDoneInstances stored procedure deletes all completed or stopped XLANG schedule instances. The following code is an example for using this stored procedure:

exec sp_CleanDoneInstances @CompletedBefore='2000-10-25 19:34:49.000'

Notes

  • The time is in Greenwich mean time because all date and time information is stored in the Orchestration Persistence database in this format.

  • The completion time applies only to the root-level schedules.

sp_CleanDoneModuleInstances @CompletedBefore='<GMT date and time>', @ModuleGUID='<globally unique identifier>'

The sp_CleanDoneModuleInstances stored procedure deletes all completed or stopped XLANG schedule instances of a particular type of schedule. The following code is an example for using this stored procedure:

exec sp_CleanDoneModuleInstances @CompletedBefore='2000-10-25 19:34:49.000',
@ModuleGUID='4C5842DA-40E5-40B8-AF03-BC5DD4B7E037'

Notes

  • The time is in Greenwich mean time format because all date and time information is stored in the Orchestration Persistence database in this format.

  • The completion time applies only to the root-level schedules.

  • @ModuleGUID is the ModuleID of a schedule.

    ModuleID is a unique reference to a specific type of XLANG schedule. You can use the @ModuleGUID parameter to filter on the type of XLANG schedule. The @CompletedBefore parameter filters for XLANG schedule instances that ended before a specific time and the @ModuleGUID parameter filters for XLANG schedules that are of a certain type. You can use XLANG Monitor to determine the ModuleID for an XLANG schedule. The ModuleID is one of the properties in the events for ScheduleStart, ScheduleDone, ContextEnter, ContextLeave, TransactionBegin, and TransactionEnd. You can use also the public interface to XLANG schedule instances, IWFWorkflowInstance::ModuleId Property, to obtain the ModuleID.

sp_CleanInstance@InstanceID='{<globally unique identifier>}'

The sp_CleanInstance stored procedure deletes a completed or stopped XLANG schedule and all child instances of that schedule. This deletion operation is transactional. In this stored procedure, @InstanceID is the globally unique identifier (GUID) that is the instance identifier of the root XLANG schedule. BizTalk Server 2002 uses this stored procedure. You are not required to call this stored procedure directly. Instead, you should follow the instructions for purging the XLANG database.

Note

  • You can create SQL Server Agent jobs to use these stored procedures at regular intervals. For more information, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.


Shut down all XLANG applications

You must follow this procedure to perform a controlled shutdown for all COM+ applications. This enables you to shut down all running XLANG schedules by saving their state to the persistence database. For more information, see Persistence.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click XLANG Scheduler.

  4. On the Action menu, click Properties.

    The XLANG Scheduler Properties dialog box appears.

  5. On the XLANG tab, in the Controlled shutdown area, click All XLANG Applications.

Caution

  • Do not right-click a COM+ application and click Shut down. One of the following might occur:
    • If running XLANG schedules are fully transactional, an uncontrolled shutdown causes any executing transactions to abort.

    • If running XLANG schedules are not fully transactional, data that is in process in the schedule is lost.

Important

  • You cannot restart dehydrated XLANG schedules if the data source name (DSN) is not available or if it is incorrectly configured. For more information about configuring a DSN for the default XLANG Scheduler application, see Change the application identity for the default XLANG Scheduler application.

Notes

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Change the application identity for the default XLANG Scheduler application

Restart all XLANG applications

Running XLANG Schedules

Run XLANG Schedules

Shut down a COM+ application that hosts XLANG schedules


Restart all XLANG applications

You must follow this procedure to perform a controlled restart for all COM+ applications.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click XLANG Scheduler.

  4. On the Action menu, click Properties.

    The XLANG Scheduler Properties dialog box appears.

  5. On the XLANG tab, in the Restart dehydrated XLANG applications area, click All XLANG Applications.

Important

  • You cannot restart dehydrated XLANG schedules if the data source name (DSN) is not available or if it is incorrectly configured. The data source name (DSN) and the COM+ application must be the same. For example, if the COM+ application hosting the XLANG Scheduler Engine is called XLANG Scheduler, the DSN must also be called XLANG Scheduler.

  • When you restart dehydrated applications, this process starts the rehydration of the dehydrated schedules asynchronously. The rehydration process is not immediate. Use XLANG Event Monitor to determine when the rehydration process is complete. For more information about the XLANG Event Monitor tool, see the Readme.htm file associated with the tool. Both XLANG Event Monitor (XLANGMon.exe) and the readme installed by the Microsoft BizTalk Server 2002 Setup Wizard are located in the following installation directory: \Program Files\Microsoft BizTalk Server\SDK\XLANG Tools.

Notes

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Change the application identity for the default XLANG Scheduler application

Running XLANG Schedules

Run XLANG Schedules

Shut down a COM+ application that hosts XLANG schedules

Shut down all XLANG applications


Manage the Default XLANG Scheduler Application

The default XLANG Scheduler application hosts the default instance of the XLANG Scheduler Engine created during the installation of BizTalk Server 2002. On production systems or systems running Microsoft Terminal Server, you need to change the default identity for this application.

For more information about security and performance issues related to changing the default settings for the default XLANG Scheduler application, see Security for Applications That Host XLANG Schedule Instances.

The following procedure is covered in this section:

  • Change the application identity for the default XLANG Scheduler application

Notes

  • For more information about Microsoft SQL Server, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Create a COM+ application to host XLANG schedules

Running XLANG Schedules

Run XLANG Schedules


Change the application identity for the default XLANG Scheduler application

It is recommended that you change the default interactive user account for the default XLANG Scheduler application to a service account. With an interactive user account, if a user is not logged on, the application will not run. By changing the interactive account to a service account, a specific user does not have to be logged on all the time. A service account is an account with specific properties that allow the account to act as part of the operating system. For more information about security and performance issues related to changing the default settings for the default XLANG Scheduler application, see Security for Applications That Host XLANG Schedule Instances. For more information about setting up a service account, see Set up a service account.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click XLANG Scheduler.

  4. On the Action menu, click Properties.

    The XLANG Scheduler Properties dialog box appears.

  5. On the Advanced tab, in the Permission area, clear the Disable changes check box and click OK.

    The following message appears:

    The applications were created by one or more external products. Are you certain the changes you are about to make are supported by these products?

  6. Click Yes.

    The XLANG Scheduler Properties dialog box closes.

  7. Click XLANG Scheduler.

  8. On the Action menu, click Properties.

    The XLANG Scheduler Properties dialog box appears.

  9. On the Identity tab, in the Account area, click This user.

  10. Type the information for the account that you want to use.

  11. Click OK.

    The following message appears:

    The applications were created by one or more external products. Are you certain the changes you are about to make are supported by these products?

  12. Click Yes.

Notes

  • If you are accessing XLANG Scheduler Properties through Microsoft Terminal Server, the XLANG tab will not be visible if the XLANG Scheduler account is set to Interactive user (on the Identity tab) and no user is currently logged on to the host BizTalk Server. Performing the preceding steps will correct this problem.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Change the DSN settings for a COM+ application

Create a new empty persistence database

Creating an Instantiating Application

Restart all XLANG applications

Running XLANG Schedules

Run XLANG Schedules

Shut down all XLANG applications


Manage Other COM+ Applications That Host XLANG Schedules

Although you can use the default XLANG Scheduler application to run XLANG schedules, it is often useful to create a new COM+ application to run XLANG schedule instances due to security, deployment, and configuration issues.

You might want to create a new COM+ application to host dedicated instances of running XLANG schedules to distribute the processing load, or you might want to isolate applications that run specific XLANG schedule instances from other XLANG schedules that use different applications or that run under different identities. You must take into consideration security and performance needs for the applications and the schedules. For more information, see Run XLANG Schedules and Running XLANG Schedules.

To create a new COM+ application to host XLANG schedules, you must first create the persistence database this new COM+ application will be associated with. Then you must proceed to create the new COM+ application, change the default application identity settings, configure the data source name (DSN) settings for the COM+ application, and finally, you must initialize the tables for the new persistence database. For more information about creating a new COM+ application, see Create a COM+ application to host XLANG schedules.

The following procedures are covered in this section:

  • Create a new empty persistence database

  • Change the application identity for a COM+ application

  • Change the DSN settings for a COM+ application

  • Shut down a COM+ application that hosts XLANG schedules

Notes

  • For more information about Microsoft SQL Server, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."


Create a new empty persistence database

You might want to create a new persistence database to store the schedule information for a COM+ application hosting dedicated instances of running XLANG schedules.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server for which you want to add a new database, and then expand Databases.

  3. Click Databases.

  4. On the Action menu, click New Database.

    The Database Properties dialog box appears.

  5. On the General tab, in the Name box, type a name for the new database and click OK.

This action creates a new database with the default values set. You can change the default values.

Note

  • For more information about SQL Server, on the Start menu, point to Programs, point to Microsoft SQL Server, and then click Books Online.

Related Topics

Change the application identity for the default XLANG Scheduler application

Running XLANG Schedules

Run XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Change the application identity for a COM+ application

After you have created the new COM+ application that is going to host the XLANG schedule, you need to modify the user information. For more information about creating a new COM+ application to host XLANG schedules, see Create a COM+ application to host XLANG schedules.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click the COM+ application for which you want to change the identity and, on the Action menu, click Properties.

    The Properties dialog box for the selected COM+ application appears.

  4. On the Advanced tab, in the Permission area, verify that the Disable changes check box is cleared and click OK.

    The Properties dialog box closes.

  5. Right-click the COM+ application again and click Properties.

    The Properties dialog box for the selected COM+ application appears.

  6. On the Identity tab, in the Account area, click This user.

  7. Type the information for the account that you want to use.

  8. Click OK.

    The following message appears:

    The applications were created by one or more external products. Are you certain the changes you are about to make are supported by these products?

  9. Click Yes.

Notes

  • For more information about security and performance issues and the application identity settings for a COM+ application that hosts XLANG schedules, see Security for Applications That Host XLANG Schedule Instances.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, double-click Component Services, and then click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Change the application identity for the default XLANG Scheduler application

Running XLANG Schedules

Run XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Change the DSN settings for a COM+ application

When creating a new empty persistence database, you need to create the data source name (DSN) settings for the COM+ application hosting XLANG schedules that will be associated with this new persistence database. You also need to initialize the database tables.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click the COM+ application for which you want to change DSN settings.

  4. On the Action menu, click Properties.

    The Properties dialog box for the selected COM+ application appears.

  5. On the XLANG tab, select the Use file DSN check box.

  6. Click Create DSN.

    The ODBC Data Source Administrator dialog box appears.

  7. In the Database Required message box, read the information, and click OK.

    The Create New Data Source page appears.

  8. Select the type of data source that you want to use. Click Next.

  9. From the Select a driver for which you want to set up a data source list, select SQL Server and click Next.

  10. Make sure the name of the data source is the same as the name of the COM+ application that will host XLANG schedules, click Next, and then click Finish.

    Important

    • The DSN and the COM+ application must use the same name. For example, if the COM+ application is called XLANG Scheduler1, the DSN must also be called XLANG Scheduler1.

    The Create a New Data Source to SQL Server page appears.

  11. Select the server on which the new persistence database that will be associated with this COM+ application resides and click Next.

  12. Select the With Windows NT authentication using the network login ID check box and click Next.

  13. Select the Change the default database to check box, and select the new empty persistence database that will host this COM+ application.

  14. Click Next and click Finish.

  15. On the XLANG tab, click Initialize Tables.

    Caution

    • This procedure assumes you are using a new empty persistence database. Do not click Initialize Tables when you are using an existing persistence database. This action destroys any data already in the existing database.
  16. In the Confirm Database Initialization message box, click Yes.

Notes

  • It is possible to use the same name for a user DSN and a system DSN. If you use the same name for two DSNs, you will not be able to distinguish them on the properties page of the XLANG application.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, double-click Component Services, and then click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

  • For more information about configuring a DSN and using data sources (ODBC), click Help in the ODBC Data Source Administrator dialog box.

Related Topics

Running XLANG Schedules

Run XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Shut down a COM+ application that hosts XLANG schedules

Follow this procedure to shut down a specific COM+ application.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Click the COM+ application that hosts XLANG schedules that you want to shut down.

  4. On the Action menu, click Properties.

    The Properties dialog box for the selected COM+ application appears.

  5. On the XLANG tab, in the Controlled shutdown area, click This XLANG Application.

Caution

  • Do not right-click a COM+ application and click Shut down. One of the following might occur:
    • If running XLANG schedules are fully transactional, an uncontrolled shutdown triggers all On Failure and Compensation error-handling processes.

    • If running XLANG schedules are not fully transactional, data that is in process in the schedule is lost.

Important

  • You cannot restart dehydrated XLANG schedules if the data source name (DSN) is not available or it is incorrectly configured. For more information about configuring a DSN for a COM+ application that hosts XLANG schedules, see Configure a COM+ application to host XLANG schedules.

Notes

  • When you create a COM+ application to host XLANG schedules, the Restart dehydrated applications option is not available. For more information about how to restart dehydrated applications, see Restart all XLANG applications.

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Running XLANG Schedules

Run XLANG Schedules

Shut down all XLANG applications


Monitor Running XLANG Schedules

You can monitor running XLANG schedules by using either XLANG Event Monitor or Windows 2000 Event Viewer.

  • XLANG Event Monitor. When the XLANG Scheduler Engine executes XLANG schedules, it generates various kinds of events, showing the progress of the schedule instances. You can use XLANG Event Monitor to monitor XLANG schedule events and see the progress of the schedule instances. You can monitor all XLANG Scheduler applications, including the default XLANG Schedule application and any custom COM+ applications that you created to host XLANG schedules. XLANG Event Monitor can subscribe to all events published by the host applications on any number of local or distributed computers. XLANG Event Monitor can also store these events to a file for later analysis.

    For specific information about using XLANG Event Monitor, see the Readme.htm file associated with the tool. Both XLANG Event Monitor (XLANGMon.exe) and the readme installed by the Microsoft BizTalk Server 2002 Setup Wizard are located in the following installation directory: \Program Files\Microsoft BizTalk Server\SDK\XLANG Tools.

  • Windows 2000 Event Viewer. Windows 2000 Event Viewer publishes event messages related to XLANG schedules. For more information about using Event Viewer to view error messages, see the following references:
    • For information about configuring Event Viewer to filter for XLANG schedule error messages, see Configure Event Viewer for BizTalk Server errors.

    • For general information about Event Viewer, in Windows 2000 Server Help, in the Event Viewer chapter, see "Using Event Viewer."

Related Topic

Orchestration Services Error Messages


Troubleshooting BizTalk Server Administration

This section provides a centralized location for information related to troubleshooting BizTalk Server Administration. If you receive error messages, try to find a solution in this section.

Supplemental information related to issues discovered after this Microsoft® BizTalk™ Server 2002 documentation release are included in the Readme file located in the \Program Files\Microsoft BizTalk Server\Documentation folder.

The following topics are covered in this section:

  • Permission denied errors occur when accessing the BizTalk Server Administration MMC, BizTalk Messaging Manager, or the BizTalk Messaging Configuration object model

  • Error getting all groups from a database

  • Interchange and document size limit

  • Transaction time-out discrepancy between Component Services and BizTalk Server 2002

  • BizTalk Messaging Service does not start

  • BizTalk Messaging Service does not shut down when the server is out of memory

  • Slowed performance when deleting a large quantity of documents from the Suspended dueue

  • Output validation failure

  • Server does not return all documents in a flat-file interchange

  • Class identifier does not appear in the Preprocessor list

  • An interchange or document appears as binary data in the Suspended queue

  • BizTalk Server stopped processing documents

  • Receive function does not delete the document

  • HTTP transmission might duplicate documents

  • HTTP receive function does not work

  • Unable to connect to a SQL Server installed on a clustered server

  • Receive functions stopped processing documents

  • Error when moving a remote server to a different BizTalk Messaging Management database

  • Parsing errors

  • Authentication problems when IIS, BizTalk Messaging Manager tool, and SQL Server are on three different computers

  • Setup and Messaging Service fails when BizTalk Server 2002 communicates with SQL Server on a cluster

  • Character corruption occurs when DBCS data is sent through an SMTP messaging port

  • Redundant or simultaneous resubmission of documents might create duplicate instances

Notes

  • You can also check the error messages in the Suspended queue for more troubleshooting information. For more information about the Suspended queue, error messages, and possible actions, see Suspended Queue.

  • You can also check the Event Log for detailed information, such as error and warning messages. For more information about the Event Log, see Manage Event Viewer.


Permission denied errors occur when accessing the BizTalk Server Administration MMC, BizTalk Messaging Manager, or the BizTalk Messaging Configuration object model

Cause: BizTalk Server 2002 Setup adds the local group BUILTIN\Administrators to the BizTalk Server Administrators group. However, a user that belongs to the Administrators group but who does not belong explicitly to the BizTalk Server Administrators group will encounter permission denied errors when accessing the BizTalk Server Administration Microsoft Management Console (MMC), BizTalk Messaging Manager, or the BizTalk Messaging Configuration object model.

Solution: Use the Computer Management console to add individual users explicitly to the BizTalk Server Administrators group.


Error getting all groups from a database

Cause One: The BizTalk Messaging Management database is offline if you receive the following message:

Instances of Microsoft BizTalkServer_Group cannot be enumerated: The connection to the BizTalk Messaging Management database could not be opened.

Solution: Find out why the server is offline and retry the connection when it is back online. For example, you could receive this message if the server that hosts the BizTalk Messaging Management database is offline for maintenance.

Cause Two: The BizTalk Server Messaging service account does not have access to Microsoft® SQL Server™.

Solution: Make sure the BizTalk Server Messaging service account is granted access to SQL Server. For more information, see Create a SQL login and grant it database access.


Interchange and document size limit

In general, most software is designed to process relatively small files — for example, files less than 20 MB — versus large files. Therefore, if you want to process large files using BizTalk Server, you may encounter some difficulties. To process files, software needs a variety of resources, such as RAM, virtual memory, hard disk space, time to process, read buffer size, and so on. Typically, a computer first reads the entire file into RAM and then processes it. If the file is larger than 20 MB, the computer may have difficulties processing it because the resources cannot handle the file size. For example, the maximum size of the buffer resources might not be large enough, there might not be enough RAM on the computer into which to read the file, or you might run out of hard disk space.

If you receive files larger than 20 MB in size, and if you do not make any modifications to the size of the file before you submit the file to BizTalk Server for processing, BizTak Server might not be able to process the file appropriately. If you receive files 20 MB or larger, it is recommended that you break the file into smaller pieces and then submit the smaller pieces to BizTalk Server for processing. For more information about how to process large files with BizTalk Server 2002 and overcome some of the computer hardware challenges posed by large documents, go to MSDN and search for the article "Processing Large Files with BizTalk Server 2002." This paper and its accompanying sample show you how to break large documents into smaller pieces, submit them to BizTalk Server for processing, and then reassemble the pieces in their original order by using a custom preprocessor and a custom AIC.

If you plan to receive interchanges in XML Unicode format that are larger than 20 MB and if you do not plan to break the large document into smaller pieces before submitting it to BizTalk Server for processing, it is advisable to turn off global tracking settings. If you plan to receive ANSI flat-file interchanges that are larger than 7-10 MB in size and if you do not plan to break the document into smaller pieces before submitting it to BizTalk Server for processing, it is advisable to turn off tracking of the interchange body and document body, and turn off document logging in the channel configurations. For more information about configuring tracking settings for a server group, see Configure tracking properties for a server group. For more information about channel document logging properties, see Set document logging properties.

Similarly, if you plan to receive document instances in XML Unicode format that are greater than 20 MB and if you do not plan to break the large document into smaller pieces before submitting it to BizTalk Server for processing, it is advisable to turn off document logging settings in BizTalk Messaging Manager. Or, if you plan to receive ANSI flat files that are larger than 7-10 MB, it is advisable to turn off document logging settings in BizTalk Messaging Manager. For more information about storing copies of specific document instances, see Set document logging properties.

Related Topics

Configure tracking properties for a server group

Set document logging properties


Transaction time-out discrepancy between Component Services and BizTalk Server 2002

There is a file time-out discrepancy between Component Services and BizTalk Server 2002. When sending a file that exceeds the default transaction time-out value of 60 seconds through BizTalk Server 2002, BizTalk Server records the transaction as sent, and the receiving server receives the file without errors. Component Services records the transaction as aborted. Transactions cannot be rolled back.


BizTalk Messaging Service does not start

Cause: The BizTalk Server Messaging service account does not have access to SQL Server. The BizTalk Messaging Service does not start if BizTalk Server cannot connect to the SQL Server that stores the BizTalk Messaging Management database.

Solution: Verify the BizTalk Server connection to the BizTalk Messaging Management database. Verify that Microsoft SQL Server is running properly. You might need to create a service account under which to run BizTalk Server. For more information about creating a service account, in Microsoft® Windows® 2000 Help, in the Services chapter, see "Select a user account that a service will use to log on." Make sure the BizTalk Server Messaging service account is granted access to SQL Server. For more information, see Create a SQL login and grant it database access.


BizTalk Messaging Service does not shut down when the server is out of memory

Cause: If the server on which BizTalk Server is installed runs out of memory, the BizTalk Messaging Service still attempts to process documents. All documents are placed on the Suspended queue.

Solution: Restart the BizTalk Messaging Service.


Slowed performance when deleting a large quantity of documents from the Suspended queue

Cause: You might experience slow performance when you delete a large quantity of documents from the Suspended queue.

Solution: If you need to delete all documents from the Suspended queue, you might want to use PurgeBizTalkSuspendedQueue.vbs, a sample Microsoft® Visual Basic® script that is provided for this purpose. After BizTalk Server 2002 installation, you can find this script in the \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Miscellaneous folder.

Caution

  • Do not use this script unless you want to permanently delete the entire contents of the Suspended queue for the specified BizTalk Server group.


Output validation failure

Cause One: The data type of a field in the source specification does not match the data type of the field to which it is linked in the destination specification. This failure is logged to the Event Viewer.

Solution: Correct the data type in either the source or destination specification. For more information about source and destination specifications, see Create and Validate Specifications.

Cause Two: A functoid is linked to a field in the destination specification, and the field data type property is not a string.

Solution: In the destination specification, change the field data type to String. Submit the document to BizTalk Server for processing. For more information about data types, see Set declaration properties.

Cause Three: In the destination specification, a field is assigned a constant value that uses a different data type than the data type already assigned to the field.

Solution: In the destination specification, change the data type associated with the field. Submit the document to BizTalk Server for processing. For more information about data types, see Set declaration properties.

Cause Four: Release indicators are included in EDIFACT data. The release characters are included in the logical character count when validating the maximum physical character limit for a field. This failure is logged to the Event Viewer.

Solution: Do not use release indicators in EDIFACT data. BizTalk Server automatically inserts release indicators in outbound data when needed.

Related Topics

Create and Validate Specifications

Set declaration properties


Server does not return all documents in a flat-file interchange

Cause: One of the documents in the interchange does not meet the document specification. For example, one of the documents is missing a required field.

Solution: Locate the document that does not meet the specification, fix it, and resubmit the interchange. Although an error is returned for the document that does not meet the specification, BizTalk Server cannot process all the documents in the interchange. The flat-file structure is an open format and is not designed to implement redundancy checking.


Class identifier does not appear in the Preprocessor list

Cause: The custom preprocessor is not properly registered.

Solution: Register the custom preprocessor again or choose another preprocessor from the list.

Related Topics

Configure a File Receive Function: Services Tab

Custom Preprocessors

Preprocessing Documents in a Receive Function


An interchange or document appears as binary data in the Suspended queue

Cause One: BizTalk Server could not parse the interchange or document.

Solution: Delete the document from the Suspended queue. Verify that the incoming interchange or document is in a format that BizTalk Server can process (XML, X12, EDIFACT, or flat file). Submit it to BizTalk Server from the original organization or application again.

If BizTalk Server cannot parse a document, it appears as binary data in the Suspended queue because BizTalk Server does not have enough information to read and process the document correctly. For more information about parsing errors, see Parsing errors.

Cause Two: BizTalk Server was able to parse the interchange or document, but the data content was not valid. The timestamp "expiresAt" expired and the document is no longer valid. This failure occurs in BizTalk Framework documents that use the expiredAt field.

Solution: Delete the document from the Suspended queue. This document is no longer valid. Investigate why the document is no longer valid.

Cause Three: BizTalk Server could not parse the document because the schema for the document is incorrect. If you receive a flat file and the code page for the document specification is set to UTF-8, BizTalk Server cannot parse the document because UTF-8 is not supported.

Solution: If you receive a flat file, check to see if the document specification is correct. If the code page for the document specification is set to UTF-8, BizTalk Server cannot process the document. Delete the document from the Suspended queue. For more information, see Set reference properties.

Related Topics

Parsing errors

Set reference properties

Suspended Queue


BizTalk Server stopped processing documents

Cause One: BizTalk Server cannot continue processing documents if the connection to any of the three databases—BizTalk Messaging Management, Tracking, or Shared Queue—is lost or if those databases are otherwise inaccessible. This might occur if Microsoft SQL Server is shut down or paused from Enterprise Manager. If BizTalk Server 2002 encounters this error, the BizTalk Messaging Service shuts down gracefully to properly preserve the state of processing and integrity at the moment of failure. An error is logged to the Event Viewer with a full description of the error causing the service to shut down.

Solution: System administrators can use this error for notification that BizTalk Server is offline through pager notification or status delivery through e-mail. Upon such notification the administrator must manually restart the BizTalk Messaging Service through the Services Microsoft Management Console (MMC) snap-in, and then check the Event Log again to determine whether the error is still present. If it is, the administrator must confirm that SQL Server services are available to BizTalk Server. For more information about how to start the BizTalk Messaging Service, see Start a BizTalk service.

Cause Two: If you have antivirus software on the server on which BizTalk Server 2002 is installed, the default setting in a messaging port might be incorrect.

Solution: The default setting for the file transport component is to append files. If you choose the file transport type with its default settings in a messaging port and use antivirus software on the server on which BizTalk Server 2002 is installed, and you send multiple files that have exactly the same name to the same file location, at the same time, BizTalk Server 2002 might stop responding and must be restarted. You can eliminate this problem by changing the default setting for the file transport component in the BizTalk SendLocalFile Properties dialog box from Append to file to Overwrite file. You also can eliminate this problem by creating a unique file for each document instance processed by using the file path format in the messaging port: file://C:\dir\file%tracking_id%.xml. For more information, see Specify a transport address. If you need to restart the server, see Start a server in a group.

Related Topics

Specify a transport address

Start a BizTalk service

Start a server in a group


Receive function does not delete the document

Cause: The retry interval might be set below the processing capability for the number of documents generated.

Solution: Double the retry interval and resubmit the documents to BizTalk Server. For more information about configuring the retry interval, see Set advanced configuration properties.


HTTP transmission might duplicate documents

Cause: If BizTalk Server is using the HTTP transport service to send messages, there are scenarios where BizTalk Server receives a failure notification even though the transmission succeeded. An example is transmission timeout. When a timeout occurs, the connection with the HTTP server is broken and a failure is reported, even though the HTTP server might eventually successfully process the request. On failure BizTalk Server will retry the transmission because the first transmission failed, and the document might be duplicated.

Solution: To ensure that transmission over non-transacted protocols such as HTTP occurs only once, use reliable messaging. For more information, see Processing Receipts Using Reliable Messaging.


HTTP receive function does not work

Cause One: The BizTalkHTTPReceive.dll file was not properly deployed prior to creating an HTTP receive function.

Solution: Deploy the BizTalkHTTPReceive.dll file before creating an HTTP receive function. For more information about how to add an HTTP receive function, see Add an HTTP receive function.

Cause Two: If the isolation level for the IIS virtual directory containing BizTalkHTTPReceive.dll is set to low, Internet Information Services (IIS) might not have been configured to run under the identity of a user with the correct security credentials for BizTalk Server.

Solution: Configure IIS to run under the identity of a user that has access both to BizTalk Server SQL databases and the BizTalk COM+ Applications (BizTalk Server Interchange Application and BizTalk Messaging Internal Utilities), and then stop and restart the IIS service.

Cause Three: The client is not using the correct URL format and/or is not encoding for the virtual directory where Hypertext Transfer Protocol (HTTP) posts data over to the HTTP receive function.

Solution: For the HTTP receive function to work properly, when the client specifies the URL where the data should be posted over HTTP to the HTTP receive function, it is necessary that the query string is a multibyte character string (MBCS) encoded using the UTF-8 codepage. For more information, go to the MSDN Library Web site (msdn.microsoft.com/library/default.asp) and search on "Support for Multibyte Character Sets" and "Encoding.UTF8 Property."


Unable to connect to a SQL Server installed on a clustered server

Cause One: When Microsoft SQL Server is installed on a cluster, SQL Server can support only clients that connect using TCP/IP.

Solution: Install SQL Server client tools and change the default network library to TCP/IP. For more information about installing SQL Server client tools, see Install SQL Server client tools. For more information about changing the default network library, see Change the default network library to TCP/IP.

Cause Two: The BizTalk Server account does not have access to SQL Server.

Solution: Make sure the BizTalk Server Messaging service account is granted access to SQL Server.. For more information, see Security Guidelines.

International Issue

Cause Three: Installing BizTalk Server on a computer without Microsoft SQL Server installed and trying to set up a BizTalk Server database on a remote SQL Server computer that is running a different default language version of SQL Server might result in an error. The following error message might appear while running the BizTalk Server 2002 Database Setup Wizard:

Cannot open database requested in login <database name>. Login fails.

Solution: To prevent this problem, create a sample user data source name (DSN) before installing BizTalk Server.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and double-click Data Sources (ODBC).

    The ODBC Data Source Administrator dialog box appears.

  2. Click the User DSN tab and click Add.

    The Create New Data Source dialog box appears.

  3. In the Name list, click SQL Server and click Finish.

    The Create a New Data Source to SQL Server Wizard opens.

  4. Complete the Create a New Data Source to SQL Server Wizard to create a sample user DSN.

Related Topics

Change the default network library to TCP/IP

Install SQL Server client tools


Receive functions stopped processing documents

Cause One: A single remote server cannot support more than 50 receive functions at the same time.

Solution: For more information about supporting multiple receive functions, go to the Microsoft Product Support Services Web site (search.support.microsoft.com/kb/c.asp) and search the Knowledge Base for the following article:

  • "IIS Runs Out of Work Items and Causes RPC Failures When Connecting to a Remote UNC Path" (Article number Q221790)

For additional information, see the following Knowledge Base articles:

  • "Local System Account and Null Sessions in Windows NT" (Article number Q132679)

  • "Service Running As System Account Fails Accessing Network" (Article number Q124184)

  • "PRB: Access Denied When Opening a Named Pipe from a Service" (Article number Q126645)

  • "FindFirstChangeNotification May Not Notify All Processes on File Changes" (Article number Q188321)

Cause Two: If you use File receive functions, and if there are other processes that use files at the same time as BizTalk Server, it is possible that one or more File receive functions might stop processing documents and become unavailable. This occurs when BizTalk Server successfully processes a file, but cannot delete it because the file is being accessed by another application. The File receive function is disabled to ensure that the data is not processed a second time if the other application(s) stops using the file.

Solution: To prevent this problem from occurring, make sure that any files placed in folders monitored by File receive functions are not actively being used by other applications. This can include some virus protection software that monitors incoming files.

Cause Three: If the Message Queuing receive function receives a document that was sent as a pass-through submission, the receive function shuts down and the following error message is displayed:

Change this receive function to accept pass-through submissions or remove the pass-through document from the queue.

Solution: The Message Queuing receive function is not configured to accept pass-through submissions. Write an application that examines the queue for the AppSpecific property of messages in the queue to determine which document came through as a pass-through submission. Remove the document and restart the receive function.


Error when moving a remote server to a different BizTalk Messaging Management database

Cause: If you try to add a remote server to a BizTalk Messaging Management database, and that server was originally in a different central BizTalk Messaging Management database, the following error message appears in the Windows Event Log:

A new instance of the WMI class "MicrosoftBizTalkServer_Server" cannot be created in the BizTalk Server WMI provider. The <server name> server may already belong to a different BizTalk Server installation.

This error means that an attempt was made to add a remote server that was originally in a different central database. If this procedure was performed within BizTalk Server Administration, the administration console tries to determine if the remote server also belongs to a group in the remote central database. The administration console queries the Windows Management Instrumentation (WMI) provider of the remote server to make this determination. If the server does belong to a group in the other central database, an error message from the administration console appears and explains that you cannot add a remote server that already belongs to a group in a different central database.

Solution: First remove the server from the previous database, and then add it to the current database.

Related Topic

Windows Management Instrumentation (WMI)


Parsing errors

Cause One: If you are sending reliable messages, the default settings in a port might be incorrect. The default setting for the file transport component is to append files. If you choose the file transport type with its default settings and select an envelope with a reliable envelope format in a messaging port, and then send multiple files to the same file location, at the same time, you might have unexpected parsing results.

Solution: You can eliminate this problem by changing the default setting for the file transport component from Append to file to Overwrite file in the BizTalk SendLocalFile Properties dialog box. For more information about changing the default settings in a port, see Override messaging port defaults.

Other Causes: BizTalk Server cannot parse a document for a variety of reasons. Some common reasons are:

  • The interchange or document is in a format that BizTalk Server cannot understand.

  • The schema for the document is incorrect.

  • A flat-file interchange has the wrong or invalid schema.

  • A flat-file interchange contains invalid characters.

  • A flat-file interchange is missing characters.

  • A flat-file interchange is missing delimiters.

  • A BizTalk Framework 2.0 document has an invalid alias listed in the port or channel.

  • The document container node is missing in a custom XML header.

  • An attribute is missing in a custom XML document.

  • An EDI document specification does not match the envelope.

Solution: View the interchange or document data to determine why BizTalk Server could not parse the interchange or document. To view the interchange or document data, you can:

  • View the first 512 bytes of the interchange or document data. For more information about how to view interchange and document data, see View interchanges or View documents.

  • View the interchange data in the interchange record in BizTalk Document Tracking. For more information about how to view interchanges in BizTalk Document tracking, see Search by date for interchange and document information, Search by organization for interchange and document information, Search by document type for interchange and document information, or Search for interchange and document information by combining query parameters.

  • Use the Windows Management Instrumentation (WMI) layer to view the interchange data. For more information about WMI Application Programming, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search for WMI Application Programming.

Once you determine why BizTalk Server could not parse the document, correct the problem and resubmit the interchange or document using IInterchange or a receive function.

Related Topics

An interchange or document appears as binary data in the Suspended queue

Search by date for interchange and document information

Search by document type for interchange and document information

Search by organization for interchange and document information

Search for interchange and document information by combining query parameters

Suspended Queue

View documents

View interchanges


Authentication problems when IIS, BizTalk Messaging Manager tool, and SQL Server are on three different computers

Cause: If you install the BizTalk Messaging Manager tool, Internet Information Services (IIS), and Microsoft SQL Server on three separate computers, you might experience authentication problems. The authentication problems arise from a double-hop, that is, the credentials are transmitted from the BizTalk Messaging Manager tool on remote client computer A to a BizTalk Server with IIS on computer B (first hop), but IIS cannot transmit the credentials to the SQL Server configuration database on computer C (second hop).

Solution: Configure the BizTalk Messaging Manager tool (remote client), IIS, and SQL Server on two computers instead of three. The following configurations are supported:

  • BizTalk Messaging Manager tool and IIS are on the same computer, and SQL Server is on a second computer.

  • BizTalk Messaging Manager tool is on one computer (remote computer), while IIS and SQL Server are on a second computer.

For more information about IIS authentication, go to the Microsoft Product Support Services Web site (search.support.microsoft.com/kb/c.asp) and search the Knowledge Base for the article "INFO: How IIS Authenticates Browser Clients" (article number Q264921).

Caution

  • BizTalk Server must be installed in the same computer as IIS.

Note

  • This double-hop authentication problem also occurs when the BizTalk Messaging Manager tool and the SQL Server configuration database are on the same computer, and BizTalk Server and IIS are on a second computer. Note that this is not a supported configuration.


Setup and Messaging Service fails when BizTalk Server 2002 communicates with SQL Server on a cluster

When BizTalk Server 2002 is installed on a stand-alone computer with SQL Server databases running on a Microsoft Cluster service cluster, the setup program fails during the BizTalk Messaging Management database setup with the following error:

BizTalk Server failed to access the <BizTalk Messaging Management database name> database on the <SQL Server> server with the database connection information.

This is a problem with the SQLOLEDB provider in MDAC 2.6. To resolve this issue, upgrade to MDAC 2.7 (when it becomes available).


Character corruption occurs when DBCS data is sent through an SMTP messaging port

International Issue

Cause: If you installed Microsoft Data Access Components (MDAC) 2.5 and configured an SMTP messaging port to have Multipurpose Internet Mail Extensions (MIME) encoding, when double-byte character set (DBCS) data is sent through that port, the data will return corrupt. (MDAC 2.5 comes with all Windows 2000 Service Pack versions.)

Solution: To avoid this issue, install MDAC 2.6. You can install MDAC 2.6 in one of the following ways:

  • To install MDAC 2.6 directly, open your browser and go to the Microsoft Universal Data Access Web site (www.microsoft.com/data) to download it.

  • Install SQL Server 2000 client utilities that include MDAC 2.6.

At this time, no fix is available that works on both MDAC 2.5 and MDAC 2.6.


Redundant or simultaneous resubmission of documents might create duplicate instances

Cause: If multiple users, or multiple instances of BizTalk Server Administration, are resubmitting batches of the same documents at the same time, duplicate instances might be created in the Work queue.

Solution: Do not resubmit the same groups of documents from multiple instances at the same time.


Tracking Documents

BizTalk Document Tracking is a stand-alone Web application that you can use to view the progress of documents processed by Microsoft® BizTalk™ Server 2002. You can create queries or advanced queries to extract essential information from the Tracking database in an easy-to-view format. For example, in BizTalk Document Tracking you can view captured information about the document source and destination, the document name and document type, and relevant date and time parameters. You can also create queries that display standard and custom-search fields so you can analyze your business practices. For example, a Purchase Order Total field can be stored for every purchase order sent to suppliers. You can then use this data to analyze and report the monetary volume of purchases to one or several suppliers over a period of time.

In addition, you can configure BizTalk Document Tracking to display interchange and document records individually or in batches. You can also use BizTalk Document Tracking to display, view, and save complete copies of the incoming and outgoing document instances for future reference.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Document Tracking, see About BizTalk Document Tracking.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Document Tracking Tasks.

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Document Tracking Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk Document Tracking.

Important

  • Because BizTalk Document Tracking is accessed as a Web application by using Microsoft Internet Explorer, Microsoft BizTalk Server 2002 Help is accessed differently and Help functionality is somewhat restricted. The Table of Contents, Index, Search, and Favorites tabs are not available. You can access all topics through links from the opening page and through Related Topics links, as well as, the Back button on the browser.

    If you want to search for a specific Help topic, or if you want to access information about other features and services of BizTalk Server 2002, on the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Documentation. For Help to be available from the Start menu, BizTalk Server 2002 must be installed on your computer.

  • Because BizTalk Document Tracking uses Microsoft ActiveX® Controls, an ActiveX control download dialog box might appear during selections or query submissions. If this happens, click Yes to continue.

Note

  • A dialog box with the following message might appear during selection or query selection:

    This page accesses data on another domain. Do you want to allow this?

    To avoid this message in Internet Explorer, you can add a secure Web site to the Trusted sites zone on the Security tab of the Internet Options dialog box.

    To manually configure the settings on your browser to trust this Web application, add the Web application to the list of trusted sites in Internet Explorer. For more information about adding the Web application to the list of trusted sites, see Configure IIS settings for BizTalk Server 2002.


About BizTalk Document Tracking

This section provides detailed conceptual information that is essential to understanding tracking documents and monitoring activities.

The following topics are covered in this section:

  • BizTalk Document Tracking Environment

  • Using BizTalk Document Tracking

  • Understanding the Tracking Database Schema

  • Understanding How to Find Interchanges and Associated Documents

  • Understanding Query Results

  • Understanding Integrated XLANG Schedule Status for an Interchange

Note

  • A dialog box with the following message might appear during selection or query selection:

    This page accesses data on another domain. Do you want to allow this?

    To avoid this message in Internet Explorer, you can add a secure Web site to the Trusted sites zone on the Security tab of the Internet Options dialog box.

    To manually configure the settings on your browser to trust this Web application, add the Web application to the list of trusted sites in Internet Explorer. For more information about adding the Web application to the list of trusted sites, see Configure IIS settings for BizTalk Server 2002.


BizTalk Document Tracking Environment

The following topics are covered in this section:

  • BizTalk Document Tracking User Interface

  • BizTalk Document Tracking Shortcut Keys


BizTalk Document Tracking User Interface

BizTalk Document Tracking is a stand-alone Web application that you can use to view interchanges and documents that you configured to be tracked in Microsoft BizTalk Server. The main page contains six areas:

  • Date Range

  • Source Selection

  • Destination Selection

  • Advanced Query

  • Sort Control

  • Document Type Selection

You can configure query parameters in the Date Range, Source Selection, Destination Selection, and Document Type Selection areas.

The lower-left side of the page contains the Advanced Query and Sort Control areas. Configure parameters in the Advanced Query area to find specific information or custom search fields. Configure options in the Sort Control area to specify the sort order on the Query Results page.

When you click the Query button on the main page, the Query Results page appears. If any records in the Tracking database match your query parameters, interchange records appear in a list. The following table lists and describes the icons that are available on the Query Results page.

Click this icon | To
Data icon | Access the interchange or document instance data. If you click the Data icon in the interchange record, the interchange data appears. If you click the Data icon in the document instance record, the document data appears.
Expand indicator icon | Expand the interchange record to view the document instance record.
Collapse indicator icon | Collapse the interchange record to hide the document instance record.
XLANG schedule icon | View the XLANG schedule status related to an interchange.
Receipt icon | View a new Query Results page to view the receipt contents. For more information about receipt results, see Understanding Receipt Results.
Custom search icon | View the custom search data.


BizTalk Document Tracking Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Document Tracking. The following table is a quick reference to the shortcut keys available on the main page.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server Help, see "Using the keyboard to move the mouse pointer." In Windows 2000 Professional Help, see "To move the mouse pointer by using MouseKeys."
Press | To
ALT+N | Open the Advanced Query Builder page.
ALT+B | Open the Advanced Queries page.
ALT+C | Clear the advanced query from the current query session.
ALT+S | Select all organizations and applications in the Source Selection list.
ALT+R | Clear the Source Selection list.
ALT+E | Select all organizations and applications in the Destination Selection list.
ALT+A | Clear the Destination Selection list.
ALT+W | Show all document types in the Document Type Selection list.
ALT+T | Select all document types in the Document Type Selection list.
ALT+L | Clear the Document Type Selection list.
ALT+Q | Open the Query Results page.
ALT+O | Close BizTalk Document Tracking.
ALT+H | View online Help.
ALT+Underlined letter or number of a field name | Move the focus to that particular field. For example, ALT+1 moves the focus to Sort order 1.

The following table lists and describes the shortcut keys available on the Query Results page. To open the Query Results page, on the main page, press ALT+Q.

Press | To
ALT+C | Close the Query Results page.
ALT+H | View online Help.
SPACEBAR | Open or close an icon. You must use the TAB key to place the focus on the icon that you want to open or close. For example, if you want to expand an interchange record, press TAB until the focus is on the expand indicator (+) for the selected interchange record. Then press SPACEBAR.

The following table lists and describes the shortcut keys available on the Advanced Query Builder page. To open the Advanced Query Builder page, on the main page, press ALT+N.

Press | To
ALT+N | Add a condition to the advanced query expression.
ALT+E | Edit a condition.
ALT+R | Remove a condition from an advanced query expression.
ALT+S | Save the expression.
ALT+O | Limit the use of the expression to the current query session.
ALT+C | Close the Advanced Query Builder page.
ALT+H | View online Help.
ALT+Underlined letter of a field name | Move the focus to that particular field. For example, ALT+V moves the focus to the Value field.

Note

  • If you move the focus to the Query area and there is more than one condition in the Query area, use the UP and DOWN arrow keys to select the condition you want.

The following table lists and describes the shortcut keys available on the Advanced Queries page. To open the Advanced Queries page, on the main page, press ALT+B.

Press | To
ALT+E | Edit an existing expression.
ALT+N | Open the Advanced Query Builder page.
ALT+D | Delete an expression.
ALT+O | Add the expression to the current query.
ALT+C | Close the Advanced Queries page without saving your changes.
ALT+H | View online Help.


Using BizTalk Document Tracking

You can use BizTalk Document Tracking to do the following:

  • Track interchanges and associated documents processed by Microsoft BizTalk Server 2002.

  • Fulfill legal and/or standards requirements to keep copies of all electronic business transactions.

  • Answer customer questions quickly and easily. For example, if a customer asks "When did we send trading partner A an invoice?", you can locate the date, time, and whether the trading partner returned a receipt.

  • Aid in troubleshooting.

  • Help resolve disputes.

Documents can be tracked either in batches or as single transactions. BizTalk Document Tracking automatically stores metadata associated with an interchange, such as source and destination information, document type, and date and time parameters. Metadata is stored automatically; however, additional fields, such as Purchase Order Date or Purchase Order Total, are captured only if you configure the BizTalk Messaging Configuration object model or BizTalk Messaging Manager to capture this information. For more information about configuring selected fields to be tracked, see Set Channel Properties and Set Tracking for Inbound Document Properties.

All tracking information—either the metadata or the fields that you configured to be tracked—is stored in the Tracking database that you configured during installation or when you configured a server group. Through the BizTalk Document Tracking user interface (UI), you can access the data stored in the Tracking database associated with a particular server group. While not all the information that is stored in the Tracking database is available through the user interface, the metadata and the fields that you configured to be tracked are readily available. For example, if you need to track when purchasing application C sent a purchase order to trading partner D and if and when trading partner D responded to the purchase order, this task can be accomplished using BizTalk Document Tracking.

The following topics are covered in this section:

  • Understanding Tracking Settings for a Server Group

  • Understanding Tracking Settings in BizTalk Messaging Manager

Note

  • Reliable messaging receipts are not displayed in the BizTalk Document Tracking user interface.

Related Topics

Set Channel Properties

Set Tracking for Inbound Document Properties

Tracking Database


Understanding Tracking Settings for a Server Group

Tracking settings for a server group determines whether tracking of interchanges is enabled or disabled. This global tracking setting is configured in BizTalk Server Administration. For more information about configuring tracking settings for a server group, see Configure tracking properties for a server group. If the Enable document tracking option is selected, you can configure BizTalk Server to log incoming interchanges, log outgoing interchanges, and/or log the original MIME-encoded messages.

When you install Microsoft BizTalk Server 2002, document tracking is automatically enabled, the log incoming interchange and log outgoing interchange options are selected, and the metadata for interchanges is tracked, such as:

  • Source organization information

  • Destination organization information

  • Document type

  • Date and time the interchange was processed by BizTalk Server

  • Document count

  • Error information

  • Control ID

In addition to tracking interchanges, you can also configure BizTalk Server to track specific fields, such as Purchase Order Total or Invoice Total. For more information about tracking specific fields, see Understanding Tracking Settings in BizTalk Messaging Manager. If you need to keep a copy of interchanges in their original format for non-repudiation and commerce law concerns, use the global tracking settings. If you want to create an audit trail for internal purposes, or if you want easy access to data on a per-document basis, configure tracking settings in the BizTalk Messaging Configuration object model or in BizTalk Messaging Manager; however, this can cause your Tracking database to grow quickly in size and you will store duplicate data.

Disabling BizTalk Document Tracking settings

If you have no need to track documents, you can disable BizTalk Document Tracking. However, if you disable document tracking, you lose important functionality. For example, if document tracking is disabled, you cannot:

  • Track interchanges and associated documents as they pass through BizTalk Server 2002.

  • Fulfill legal and/or standards requirements to keep copies of all electronic business transactions.

  • Answer customer questions quickly and easily. For example, if a customer asks "When did we send trading partner A an invoice?", you cannot locate the date, time, and whether they returned a receipt.

  • Aid in troubleshooting.

  • Help resolve disputes.

To enable or disable document tracking, or to change global tracking settings, use BizTalk Server Administration. For more information about configuring tracking settings for a server group, see Configure tracking properties for a server group.

Notes

  • To open BizTalk Server Administration, on the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  • There is a size limit for tracking interchanges and documents. For more information about the size limit, see Interchange and document size limit.

Related Topics

Configure tracking properties for a server group

Interchange and document size limit

Open BizTalk Server Administration

Understanding Tracking Settings in BizTalk Messaging Manager


Understanding Tracking Settings in BizTalk Messaging Manager

Configure tracking settings in BizTalk Messaging Manager if you need to:

  • Store complete copies of incoming and outgoing document instances.

  • Configure specific fields, such as Purchase Order Total or Purchase Order Date, to be captured.

Unlike tracking properties for a server group, tracking specific fields or storing copies of document instances is not automatically enabled. You must configure these options when you configure the appropriate channel(s) and/or document definition(s) in BizTalk Messaging Manager.

For more information about storing copies of incoming or outgoing document instances, see Set document logging properties. For more information about tracking specific fields, see Select specification fields in a channel.

Notes

  • To open BizTalk Messaging Manager, on the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  • There is size limit for tracking and storing documents. For more information about the size limit, see Interchange and document size limit.

  • When tracking specification fields as an Integer, Real, Date, or Text data type, specification field names that exceed 79 characters are truncated.

    Track these specification fields as a Custom data type. By doing this, the field names are stored together with the field values in an SQL ntext column, which holds a maximum length of 2^30 - 1 (1,073,741,823) characters.

  • If you are unable to locate details and the receipt status for a document, in BizTalk Server Administration, the Enable document tracking check box might not be selected. If this check box is not selected, receipts cannot be correlated.

    To enable document logging, complete the following steps:

    1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and click BizTalk Server Administration.

    2. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, right-click the BizTalk Server group for which you want to change document tracking settings, and then click Properties.

    3. On the Tracking tab, select the Enable document tracking check box.

    Select any other options that you want to use.

International Issue

  • Depending on the system locale, a numeric value in XML data might be misinterpreted by BizTalk Server when logged as an Integer tracking field in the Tracking database. For example, in a German locale, an XML Number value of 4.0 is logged as 40 in the Tracking database because the decimal point (.) is misinterpreted as the digit grouping symbol.

    There are two workarounds for this issue. First, if you know in advance that the element/attribute value stores a decimal number, you can change the XML element/attribute data type to Real (r4) or Double Real (r8). Second, you can configure the document definition or channel to log an element/attribute with a Number data type as Real instead of Integer.

Related Topics

Interchange and document size limit

Select specification fields in a channel

Set document logging properties

Understanding Tracking Settings for a Server Group


Understanding the Tracking Database Schema

All servers in a server group share a single Tracking database that stores all information related to interchange and document activity in Microsoft BizTalk Server 2002. The Tracking database is used to track the status of an interchange or document as it moves through the server. The three main tables in the Tracking database are:

  • dta_interchange_details

  • dta_outdoc_details

  • dta_indoc_details

The supporting tables are:

  • dta_group_details

  • dta_interchange_data

  • dta_document_data

  • dta_debug_data

  • dta_routing_details

  • dta_custom_field_names

  • dta_MIME_data

The following illustration shows the overall database schema of the Tracking database. For clarity, only the table names are listed in the following illustration. The lines that connect the tables together demonstrate how the tables are connected through foreign key fields. These key fields and their relationships to other tables are described in detail in the topics Metadata Core Table Structure and Structure of Secondary Tables.

Tracking database schema

The following topics are covered in this section:

  • Metadata Core Tables

  • Secondary Tables

  • Metadata Core Table Structure

  • Structure of Secondary Tables

  • Related Tables

  • How Interchanges and Documents Are Logged

  • How Receipts Are Logged

  • How Routing Information Is Logged

  • Tracking XLANG Schedule Events in the Tracking Database


Metadata Core Tables

The core tables store the metadata for interchanges processed by BizTalk Server. Metadata includes source and destination organization information, document type, date and time the interchange was processed, document count, error information, and control identification.

The following three tables form the metadata core of the Tracking database:

  • dta_indoc_details

  • dta_outdoc_details

  • dta_interchange_details

The following table describes the function of each core table.

Table name | Description
dta_indoc_details | Contains one record for each document submitted to BizTalk Server.
dta_outdoc_details | Contains one record for each document generated by BizTalk Server. One document submitted to BizTalk Server could result in one or more documents generated and delivered to a set of respective destinations due to multiple channel matching and port groups. Separation of in and out documents into two tables allows physical representation of this one-to-many relationship.
dta_interchange_details | Contains one record for each interchange processed by BizTalk Server. A direction flag on this table distinguishes submissions from transmissions.

Related Topic

Metadata Core Table Structure


Secondary Tables

The seven secondary tables that support the metadata core tables are:

  • dta_document_data

  • dta_debugdoc_data

  • dta_interchange_data

  • dta_routing_details

  • dta_group_details

  • dta_custom_field_names

  • dta_MIME_data

These tables store supporting information, such as document data, routing information, and custom search information. The following table describes the function of each table.

Table name | Description
dta_document_data | Contains one record for every document submitted to or sent by BizTalk Server.
dta_debugdoc_data | Contains one row for every inDoc or outDoc item that is configured (on the messaging channel object) to record its interim XML format.
dta_interchange_data | Contains one row for every interchange submitted to or sent by BizTalk Server. This table also stores any response documents returned to the IInterchange::SubmitSync calling application.
dta_routing_details | Functions as a mirror of messaging ports for the purpose of eliminating a cross-database dependency on the BizTalk Messaging Management database. Specifically, it is necessary to track source and destination information relating to documents handled. This information, which comes from the BizTalk Messaging Management database, is repeated here as new permutations are encountered.
dta_group_details | Provides extensibility components (parser, serializer, and receipt correlator) for document formats that employ like-kind document groups (for example, X12 or EDIFACT) within an interchange. This table contains one row for each group parsed or serialized by these components.
dta_custom_field_names | Contains a row for each distinct capture-field node name and data type pair encountered by BizTalk Server. This table is a cross-reference for the dta_outdoc_details table, which uses a foreign key into this table for its capture field names. The dta_indoc_details table is connected to this set of field names indirectly by the existence of a foreign key pointed from the dta_outdoc_details table to its parent in the dta_indoc_details table.
dta_MIME_data | Contains one row for every MIME-encoded interchange submitted to BizTalk Server. This table provides a way for tracking MIME data that contains attachments.

Related Topic

Structure of Secondary Tables


Metadata Core Table Structure

The metadata core tables are linked together as described in this section and store the metadata for all interchanges processed by BizTalk Server, if tracking settings are configured. For more information about configuring tracking settings for a server group, see Understanding Tracking Settings for a Server Group.

dta_indoc_details

This table has a one-to-many relationship with the following table:

  • dta_outdoc_details

This table has a many-to-one relationship with the following tables:

  • dta_group_details

  • dta_interchange_details

  • dta_error_message

  • dta_validity_values

This table has a one-to-one relationship with the following tables:

  • dta_debugdoc_data

  • dta_document_data

The dta_indoc_details table contains one row per document submitted to BizTalk Server. The following table describes the fields in the dta_indoc_details table.

Field name | Description
nInDocKey | Primary key unique record identifier.
nDocumentDataKey | Foreign key to the dta_document_data table.
nDebugDocDataKey | Foreign key to the dta_debugdoc_data table for the XML form of the received document, even if the received document is XML.
nGroupKey | Foreign key to the dta_group_details table.
nInterchangeKey | Foreign key to the dta_interchange_details table.
uidTrackingGUID | Master tracking key value based on a globally unique identifier (GUID).
dtProcessedTimeStamp | Time the record was created.
nvcSyntax | Code for document syntax (XML, X12, EDIFACT, HL7, and so on). In the case of unrecognized syntax due to parsing failure or pass-through submission, this field has a value of "UNKNOWN".
nvcVersion | Version of the syntax.
nvcRelease | Release of the version.
nvcDocType | Document type or transaction set identifier.
nvcControlID | Unique control number for electronic data interchange (EDI) documents and functional groups.
nlsValid | Code that indicates validation results. Possible values are 0 (invalid), 1 (valid), or 2 (pass-through).
nError | Code that indicates the occurrence of an error. This is the foreign key to dta_error_message, the table that contains the descriptions of the error messages.

dta_outdoc_details

This table has a many-to-one relationship with the following tables:

  • dta_indoc_details

  • dta_interchange_details

  • dta_group_details

  • dta_debugDoc_data

  • dta_routing_details

  • dta_error_message

  • dta_ack_status

  • dta_data_level_values

  • dta_validity_values

This table has a one-to-one relationship with the following table:

  • dta_document_data

This table has a many-to-many relationship with the following tables:

  • dta_custom_field_names

  • dta_ack_status_values

The dta_outdoc_details table contains one row per document sent by BizTalk Server. The following table describes the fields in the dta_outdoc_details table.

Field name | Description
nOutDocKey | Primary key unique record identifier.
nInDocKey | Foreign key to the dta_indoc_details parent record.
nDocumentDataKey | Foreign key to the dta_document_data table.
nDebugDocDataKey | Foreign key to the dta_debugdoc_data table for the XML form of the outgoing document, even if the outgoing document is XML. When an outbound document is sent to a port group, only one copy of the dta_debugdoc_data record is stored, and all resulting dta_outdoc_details records point to it.
nGroupKey | Foreign key to the dta_group_details table.
nInterchangeKey | Foreign key to the dta_interchange_details table.
uidTrackingGUID | Master tracking key value based on a globally unique identifier (GUID).
dtProcessedTimeStamp | The time the record was created.
nvcSyntax | Code for document syntax (XML, X12, EDIFACT, HL7, and so on). In the case of unrecognized syntax due to parsing failure or pass-through submission, this field has a value of "UNKNOWN".
nvcVersion | Version of the syntax.
nvcRelease | Release of the version.
nvcDocType | Document type or transaction set identifier.
nvcControlID | Unique control number for EDI documents and functional groups.
nlsValid | Code that indicates validation results. Possible values are 0 (invalid), 1 (valid), or 2 (pass-through).
nError | Code that indicates the occurrence of an error. This is a foreign key to dta_error_message, the table that contains the error message descriptions.
nAckStatus | Code for the status of the receipt. This is a foreign key to dta_ack_status_values, the table that contains the receipt status descriptions.
nRoutingKey | Foreign key to the dta_routing_details table.
nReceiptFlag | Flag that indicates to which table a receipt is associated. Possible values are 1 (interchange), 2 (group), 4 (indoc), or 8 (outdoc). For more information about receipts, see How Receipts Are Logged.
nReceiptKey | Unique number that identifies the receipt. For more information about receipts, see How Receipts Are Logged.
dtReceiptDueBy | Receipt deadline timestamp, computed to be the processing timestamp.
nRealName1 | Foreign key to the dta_custom_field_names table.
rlRealValue1 | Real capture field 1. This field must be an 8-byte real value.
nRealName2 | Foreign key to the dta_custom_field_names table.
rlRealValue2 | Real capture field 2. This field must be an 8-byte real value.
nIntName1 | Foreign key to the dta_custom_field_names table.
nIntValue1 | Integer capture field 1.
nIntName2 | Foreign key to the dta_custom_field_names table.
nIntValue2 | Integer capture field 2.
nDateName1 | Foreign key to the dta_custom_field_names table.
dtDateValue1 | Date capture field 1.
nDateName2 | Foreign key to the dta_custom_field_names table.
dtDateValue2 | Date capture field 2.
nStrName1 | Foreign key to the dta_custom_field_names table.
nvcStrValue1 | String capture field 1.
nStrName2 | Foreign key to the dta_custom_field_names table.
nvcStrValue2 | String capture field 2.
nvcCustomSearch | Binary large object for concatenated string capture as XML.

dta_interchange_details

This table has a one-to-many relationship with the following tables:

  • dta_indoc_details

  • dta_outdoc_details

  • dta_group_details

  • dta_interchange_data

This table has a many-to-one relationship with the following tables:

  • dta_direction_values

  • dta_error_message

  • dta_transport_type_values

The dta_interchange_details table contains one row per interchange processed by BizTalk Server. The following table describes the fields in the dta_interchange_details table.

Field name | Description
nInterchangeKey | Primary key unique record identifier.
nInterchangeDataKey | Foreign key to the dta_interchange_data table.
nResponseDocDataKey | Foreign key to the dta_document_data table for the response document returned by the recipient of an outbound transport.
uidInterchangeGUID | Globally unique identifier (GUID) for the interchange.
uidSubmissionGUID | Globally unique identifier (GUID) for the parent submission. Note that this holds the correlation identifier (correlationID) provided from or to BizTalk Orchestration Services. This field is empty if the record is for an inbound interchange that does not come from BizTalk Orchestration Services. For inbound interchanges, this field is populated only if the interchange comes from BizTalk Orchestration Services. For outbound interchanges, this field is always populated.
dtProcessedTimeStamp | Time the record was created.
nvcSyntax | Code for document syntax (XML, X12, EDIFACT, HL7, and so on). In the case of unrecognized syntax due to parsing failure or pass-through submission, this field has a value of "UNKNOWN".
nvcVersion | Version of the syntax.
nvcControlID | Unique control number for electronic data interchange (EDI) interchanges or an identifier for BizTalk reliable messages.
nDirection | Flag indicating whether the interchange is incoming or outgoing. Possible values are 0 (outbound) or 1 (inbound). This is a foreign key to dta_direction_values, the table that contains the direction values.
dtTimeSent | Timestamp for a successful transmission.
nError | Code that indicates the occurrence of an error. This is a foreign key to dta_error_message, the table that contains the error message descriptions.
nTestMode | Test or production indicator. This field is reserved and is not used.
nvcSrcAliasQualifer | Sender qualifier value extracted from the submitted or transmitted interchange.
nvcSrcAliasId | Sender identifier value extracted from the submitted or transmitted interchange.
nvcSrcAppName | Interchange level identifier for the source application extracted from the submitted or transmitted interchange.
nvcDestAliasQualifier | Recipient qualifier extracted from the submitted or transmitted interchange.
nvcDestAliasID | Recipient identifier value extracted from the submitted or transmitted interchange.
nvcDestAppName | Interchange level identifier for the destination application extracted from the submitted or transmitted interchange.
nAckStatus | Code for the status of the receipt. This is a foreign key to dta_ack_status_values, the table that contains the receipt status descriptions.
nvcSMTPMessageID | SMTP transport message identifier (for EDIINT). This field is reserved and is not used.
nDocumentsAccepted | Number of documents accepted in the interchange.
nDocumentsRejected | Number of documents rejected in the interchange.
nTransportType | Transmission protocol indicator code. This is a foreign key to the dta_transport_type_values table.
nvcTransportAddress | Address of the transport target.
nvcServerName | Server that processed the interchange.
nNumberOfBytes | Size of the interchange, in bytes. This field represents what is tracked in the related dta_interchange_data record and can be different than what is actually transmitted. The size can be increased by additional envelope processing and data format conversion during transmission.
nNumOfTransmitAttempts | Transmission attempt counter.

Related Topic

Understanding Tracking Settings for a Server Group


Structure of Secondary Tables

The secondary tables store the supporting data for the core tables in the Tracking database. For example, the secondary tables store information such as:

  • Custom-field search data

  • Routing information

  • Interchange data

  • Document data

Data Types

The float and real data types are known as approximate data types. The behavior of float and real data types follows the IEEE 754 specification on approximate numeric data types. Approximate numeric data types do not store the exact values specified for many numbers; rather, they store an extremely close approximation of the value. For many applications, the small difference between the specified value and the stored approximation is not noticeable. At times, though, the difference is evident. Because of this approximate nature of the float and real data types, do not use these data types when exact numeric behavior is required, such as in financial applications, in operations involving rounding, or in equality checks. Instead, use the integer, decimal, money, or smallmoney data types.

BizTalk Server allows the Number data type to be tracked as an Integer data type. If the value of the number in the document exceeds the size of the Integer data type, a warning message appears. This warning message contains the value that could not be tracked.

Do not exceed the size of the Integer data type when tracking a Number data type as an Integer.

International Issues

  • Depending on the system locale, a numeric value in XML data might be misinterpreted by BizTalk Server when logged as an Integer tracking field in the Tracking database. For example, in a German locale, an XML Number value of 4.0 is logged as 40 in the Tracking database because the decimal point (.) is misinterpreted as the digit grouping symbol.

    There are two workarounds for this issue. First, if you know in advance that the element/attribute value stores a decimal number, you can change the XML element/attribute data type to Real (r4) or Double Real (r8). Second, you can configure the document definition or channel to log an element/attribute with a Number data type as Real instead of Integer.

  • The date and time selection control, the list view, and the tree view cannot display Unicode characters. Therefore, mixed language support is limited. For example, if an English computer accesses a BizTalk Server with BizTalk Document Tracking Web pages and data that include a double-byte character set (DBCS), the characters appear as question marks (?) in the English client.

dta_document_data

This table has a one-to-one relationship with the following tables:

  • dta_indoc_details

  • dta_outdoc_details

The dta_document_data table is the central repository for document storage. The following table describes the fields in the dta_document_data table.

Field name | Description
nDocumentDataKey | Primary key unique record identifier.
nCodePage | System code page (for example, 1200-Unicode, 65001-UTF-8, and so on) for the character-encoded stored data. This field has a value of -1 if BizTalk Server does not have any code page information about the data. In this case, the value of the nBLOBType field might provide information about how to interpret the data.
nBLOBType | Flag that indicates the type of data stored in the imgDocumentData field. Possible values are 0 (Unknown) or 1 (XMLDOM Loadable). XMLDOM Loadable indicates that the data can be loaded into and manipulated by the MSXML DOMDocument object. This field is a foreign key to the dta_blobtype_values table.
imgDocumentData | Storage of a document, as a binary large object.
nNumberOfBytes | Size of the document, in bytes.
nNumberOfRecords | Records or segments comprised in the document.

dta_debugdoc_data

This table has a one-to-one relationship with the following table:

  • dta_indoc_details

This table has a one-to-many relationship with the following table:

  • dta_outdoc_details

This table is a central repository for debug document storage. The following table describes the fields in the dta_debugdoc_data table.

Field name | Description
nDebugDocDataKey | Primary key unique record identifier.
ntxtDocumentData | Storage of the document, as a binary large object. This is always in Unicode.
nNumberOfBytes | Size of the document, in bytes.
dtProcessedTimeStamp | Time that the record was created.

dta_interchange_data

This table has a many-to-one relationship with the following table:

  • dta_interchange_details

The dta_interchange_data table is a central repository for interchange storage and contains one record for each interchange processed by the system. For interchanges submitted to BizTalk Server only, the nlsFile field indicates whether the stored data originally came from the file system. If the flag is set, the nvcOriginalFileName field is a universal naming convention (UNC) path to the file system location where the data originated. The imgInterchangeData field holds the data submitted, regardless of its origination.

Field name | Description
nInterchangeDataKey | Primary key unique record identifier.
nCodePage | System code page (for example, 1200-Unicode, 65001-UTF-8, and so on) for the character-encoded stored data. This has a value of -1 if BizTalk Server does not have any code page information about the data, or if the data is tracked as a result of a pass-through submission, . In this case, the value of the nBLOBType field might provide information about how to interpret the data.
nlsFile | Flag indicating file-based data submission. Possible values are 0 (non-file-based) or 1 (file-based).
nvcOriginalFileName | Universal naming convention (UNC) path to the file, if the nlsFile field has a value of 1.
nBLOBType | Flag that indicates the type of data stored in the imgDocumentData field. Possible values are 0 (Unknown) or 1 (XMLDOM Loadable). XMLDOM Loadable indicates that the data can be loaded into and manipulated by the MSXML DOMDocument object. This field is a foreign key to the dta_blobtype_values table.
imgInterchangeData | Storage of the interchange, as binary large object.

dta_group_details

This table has a one-to-many relationship with the following tables:

  • dta_indoc_details

  • dta_outdoc_details

This table has a many-to-one relationship with the following tables:

  • dta_interchange_details

  • dta_direction_values

The dta_group_details table creates one row per group processed by extensibility components for electronic data interchange (EDI). The following table describes the fields in the dta_group_details table.

Field name | Description
nGroupKey | Primary key unique record identifier.
nInterchangeKey | Foreign key to the dta_interchange_details table.
dtProcessedTimeStamp | Time the record was created.
nvcSyntax | Code for document syntax (XML, X12, EDIFACT, HL7, and so on). In the case of unrecognized syntax due to parsing failure or pass-through submission, this field has a value of "UNKNOWN".
nvcVersion | Version of the standard.
nvcRelease | Release of the version.
nvcFunctionalGroupID | Code for the type of documents in the group.
nvcControlID | Unique control number for EDI documents and functional groups.
nvcSrcAppName | Group level identifier for the source application.
nvcDestAppName | Group level identifier for the destination application.
nAckStatus | Code for the status of the receipt. This is a foreign key to dta_ack_status_values, the table that contains the receipt status descriptions.
nDirection | Flag that indicates whether the group was incoming or outgoing. Possible values are 0 (outbound) or 1 (inbound). This is a foreign key to the dta_direction_values table.
nDocumentsAccepted | Transactions accepted in the group.
nDocumentsRejected | Transactions rejected in the group.
nNumberOfBytes | Size of the interchange, in bytes.

dta_routing_details

This table has a one-to-many relationship with the following table:

  • dta_outdoc_details

The dta_routing_details table contains one row per distinct source or destination information set. Two documents might have identical routing field values at the organization or application level. In this case, these documents are differentiated by document type or some other lower-level filter. When this happens, the dta_routing_details table contains rows that are identical except for a difference in their respective parent messaging ports. This link to the parent messaging port is used to facilitate a connection between the BizTalk Messaging Manager user interface functionality and tracking. The following table describes the fields in the dta_routing_details table.

Field name | Description
nRoutingKey | Primary key unique record identifier.
nvcSrcOrgName | Source organization name, as specified on the parent channel object.
nvcSrcAppName | Source application name, as specified on the parent channel object.
nvcDestOrgName | Destination organization name, as specified on the parent messaging port object.
nvcDestAppName | Destination application name, as specified on the parent messaging port object.
nvcDistributionName | Distribution list name.
uidChannelGUID | Unique key for the parent channel based on a globally unique identifier (GUID). This is used as a channel correlation key into the BizTalk Messaging Management database.
uidPortGUID | Unique key for the parent port based on a GUID. This is a port correlation key into the BizTalk Messaging Management database.

dta_custom_field_names

This table has a many-to-one relationship with the following table:

  • dta_outdoc_details

The dta_custom_field_names table contains one row per distinct node name and data type pair captured. The following table describes the fields in the dta_custom_field_names table.

Field name | Description
nNameKey | Primary key unique record identifier.
nvcName | Text of the node name, for example, /CommonPO/Total/@POTotal.
nDataType | Data type contained in the node named.

dta_MIME_data

The dta_MIME_data table stores the incoming MIME data processed by BizTalk Server. This provides a way to track MIME data that contains attachments. The following table describes the fields in the dta_MIME_data table.

Field name | Description
nMIMEDataKey | Primary key unique record identifier.
uidSubmissionGUID | Globally unique identifier (GUID) for the parent submission.
nCodePage | System code page for character-encoded stored data in the imgMIMEData field. For MIME data, the value is 1252 (ASCII) or 1200 (Unicode).
imgMIMEData | Storage of the document as a binary large object.


Related Tables

There are 13 additional tables in the Tracking database that support the core tables or the supporting tables. These tables store information such as group and interchange correlation keys, receipt status values, and data level values. The following table describes each table and its functionality.

Table name | Function
dta_ack_status_values | Stores the receipt status values. Possible values are None, Pending, Overdue, Accepted, Accepted with errors, and Rejected.
dta_blobtype_values | Stores the binary large object types. Possible values are Unknown and XMLDOM Loadable.
dta_data_level_values | Stores the data level values used in BizTalk Server. Possible values are Interchange, Group, Incoming Document, and Outgoing Document.
dta_direction_values | Stores the direction of the interchange. Possible values are Incoming and Outgoing.
dta_error_message Stores the error messages used in BizTalk Document Tracking. Possible values are:
  • No error.

  • A custom component could not be called.

  • The interchange could not be parsed.

  • The specified channel does not exist.

  • The interchange could not be serialized.

  • The interchange could not be encoded.

  • The interchange could not be signed.

  • The interchange could not be encrypted.

  • The transmission attempt failed (a retry is pending).

  • The last transmission attempt failed.

  • The document could not be parsed.

  • The document could not be validated.

  • A valid channel could not be found.

  • The document could not be mapped.

  • A valid messaging port could not be found.

  • The document could not be serialized.
dta_group_correlation_keys | Stores the group correlation keys. The values are dynamically generated for identifying possible group candidates during receipt correlation.
dta_interchange_correlation_keys | Stores the interchange correlation keys. The values are unique and dynamically generated for identifying possible group candidates during receipt correlation.
dta_transport_type_values | Stores the transport type values. Possible values are None, HTTP, SMTP, DCOM, App Integration, Message Queuing, File, HTTPS, Open Destination, Loopback, and Orchestration Activation.
dta_ui_codepage_charset | Stores the system code pages for character encoded data.
dta_ui_user_queries | Stores the advanced queries that individual users create and save.
dta_validity_values Stores the validity values. Possible values are Not valid, Valid, and Pass-through.

A value of Pass-through indicates that the document was not parsed and validity does not apply. For more information about pass-through, see Understanding Receive Function Advanced Properties.
dta_wf_EventData | Contains one record for each property logged in relation to a monitored COM+ event fired by an XLANG schedule. Sets of multiple rows in this table share a common parent in the dta_wf_WorkFlowEvent table.
dta_wf_WorkFlowEvent | Contains one record for each monitored COM+ event fired by an XLANG schedule.


How Interchanges and Documents Are Logged

Different processing scenarios, such as open source, open destination, and pass-through, are logged differently in the Tracking database. The six common processing scenarios are Not open, Open source, Open destination, Loopback, Pass-through, and Expect receipt and Generate receipt (Expect receipt and Generate receipt are considered one scenario). The Expect receipt and Generate receipt processing scenarios are described in How Receipts Are Logged. The remaining processing scenarios are outlined in the following table.

Processing scenario | Description
Not open | Occurs when the source and destination are both explicitly declared in the receive function, the document instance, the Submit method, or the SubmitSync method.
Open source | Occurs when the source information is not explicitly declared in the channel. The channel must be marked as open source, and the submit call or the receive function must specify source openness.
Open destination | Occurs when the destination information is not explicitly declared in the messaging port. The destination is dynamically specified in the document instance, the Submit method, or the SubmitSync method. The port must be marked as open destination, and the submit call or the receive function must indicate destination openness.
Loopback | Occurs when loopback is the specified transport in a channel. Loopback returns the outbound document of a channel to the business application, component, or XLANG schedule that submitted the inbound document using the SubmitSync method. This transport type is available only for a messaging port that connects to an application and is available only through the SubmitSync method.
Pass-through | Occurs when you select the Submit with a pass-through flag option in the receive function or specify True in the PassThrough parameter in the Submit or the SubmitSync method. BizTalk Server does not process the document. This means that the document is not parsed, signed, decrypted, verified, and so on. The document is transported only by BizTalk Server.

The following table outlines what outgoing records are logged in the Tracking database.

Processing scenario | dta_interchange_details (outgoing) | dta_outdoc_details | Response document
Not open | X | X | X
Open source | X | X | X
Open destination | X | X | X
Loopback | X | X |
Pass-through | X | X | X

Notes

  • Response documents are generated only when you use the following transports: Hypertext Transfer Protocol (HTTP), Secure Hypertext Transfer Protocol (HTTPS), or application integration component (AIC). In addition, the recipient address must post return data.

  • For the pass-through scenario, the record logged in the dta_outdoc_details table is an empty record. The nlsValid field has a value of 2 to designate that this record is associated with a pass-through document, and the nSyntax field has a value of "UNKNOWN". Because BizTalk Server does not process the document, BizTalk Server cannot populate most of the fields in this table with relevant data.

The following table outlines what incoming records are logged in the Tracking database.

Processing scenario | dta_interchange_details (incoming) | dta_indoc_details | Response document
Not open | X | X | X
Open source | X | X | X
Open destination | X | X | X
Loopback | X | X |
Pass-through | X | X | X

Notes

  • Response documents are generated only when you use the following transports: HTTP, HTTPS, or AIC. In addition, the recipient address must post return data.

  • For the pass-through scenario, the record logged in the dta_indoc_details table is an empty record. The nlsValid field has a value of 2 to designate that this record is associated with a pass-through document, and the nSyntax field has a value of "UNKNOWN". Because BizTalk Server does not process the document, BizTalk Server cannot populate most of the fields in this table with relevant data.

Related Topic

How Receipts Are Logged


How Receipts Are Logged

The following illustration shows the receipt flow in Microsoft BizTalk Server 2002.

Processing receipts using channels

In this scenario:

  • The source system and the destination system use BizTalk Server.

  • The source system is sending a purchase order to the destination system, and the source system expects a receipt from the destination system for the purchase order.

  • Both systems are configured to expect and generate receipts.

When the purchase order is processed by the source system and sent to the destination system, a record is logged in the dta_outdoc_details table. The following table shows what the fields relevant to receipts in that record might look like.

Field name | Sample value | Description
nOutDocKey | 1 | Is a unique number that identifies the record.
nAckStatus | 1 | Indicates that a receipt for the document is pending.
nReceiptFlag |  | Is not populated at this time.
nReceiptKey |  | Is not populated at this time.

When the destination system receives and processes the purchase order, a record is logged in the dta_indoc_details table and two records are logged in the dta_outdoc_details table. The record in the dta_indoc_details table tracks information relevant to the purchase order. The first record in the dta_outdoc_details table tracks information relevant to the purchase order and the second record tracks information relevant to the receipt for the purchase order.

The following table shows what the fields relevant to the purchase order in the record in the dta_indoc_details table might look like.

Field name | Sample value | Description
nInDocKey | 1 | Is a unique number that identifies the record.
nDocType | CommonPO | Identifies the type of document received.

The first record logged in the dta_outdoc_details table pertains to the purchase order processed by BizTalk Server. The following table shows what the fields relevant to receipts in that record might look like.

Field name | Sample value | Description
nOutDocKey | 10 | Is a unique number that identifies the record.
nInDocKey | 1 | Links the record to the parent record in the dta_indoc_details table.

The second record logged in the dta_outdoc_details table pertains to the receipt that is generated by the purchase order. The following table shows what the fields relevant to receipts in that record might look like.

Field name | Sample value | Description
nOutDocKey | 2 | Is a unique number that identifies the record.
nInDocKey | 1 | Links the record to the parent record in the dta_indoc_details table.
nAckStatus | 0 | Indicates that the receipt does not expect a receipt in return.
nReceiptFlag | 4 | Indicates that the receipt is associated with a record in the dta_indoc_details table.
nReceiptKey | 1 | Is a unique number that identifies the receipt record.

When the source system receives the receipt generated by the destination system and a record is logged in the dta_indoc_details table, the original record logged in the dta_outdoc_details table is updated. The following table shows what the fields that pertain to receipts in the record in the dta_indoc_details table might look like.

Field name | Sample value | Description
nInDocKey | 9 | Is a unique number that identifies the record.
nDocType | 997 | Identifies the type of document received.

The following table shows what the fields that pertain to receipts in the updated record in the dta_outdoc_details table might look like.

Field name | Sample value | Description
nOutDocKey | 1 | Is a unique number that identifies the record.
nAckStatus | 3 | Indicates that a receipt was received.
nReceiptFlag | 4 | Indicates that the receipt is associated with a record in the dta_indoc_details table.
nReceiptKey | 9 | Is a unique number that identifies the receipt record.

Related Topic

How Interchanges and Documents Are Logged


How Routing Information Is Logged

The routing information logged in the Tracking database varies depending on whether the document is incoming or outgoing and how BizTalk Server processed the data. For inbound interchanges, when BizTalk Server receives a document, it views the document instance for routing information. Then, BizTalk Server checks the receive function or the routing parameters specified in IInterchange::Submit. If routing information is provided in the receive function or IInterchange::Submit, those parameters are used to route the document instance. However, the routing information supplied in the document instance is logged in the dta_routing_details table in the Tracking database.

For outbound interchanges, the source and destination routing information always comes from the channel, and this information is logged in the dta_routing_details table.

This affects what information is shown in the BizTalk Document Tracking user interface for alias information. It does not affect how interchanges submitted to and transmitted from BizTalk Server are related as a single data flow instance.


Tracking XLANG Schedule Events in the Tracking Database

Action events related to messages processed by an XLANG schedule that are exchanged between BizTalk Messaging Services and BizTalk Orchestration Services can be tracked in the appropriate tables in the Tracking database. The action events can be viewed by using BizTalk Document Tracking. However, tracking and viewing action events related to messages processed by an XLANG schedule is not automatically enabled when you install BizTalk Server 2002. To enable this feature, you must complete the following steps:

  1. Register the sample dynamic-link library (DLL) file, WorkFlowAudit.dll.

    You can find this sample file in the \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAudit\bin folder.

  2. Run the WorkFlowAuditClient.exe application, to activate WorkFlowAudit.dll.

    You can find this sample application in the \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAuditClient folder.

    For additional information, you can view the documentation (Readme.txt) found in the \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAudit\Docs folder.

  3. Click the Start button in the WorkFlowAuditClient application to initiate the logging of action events related to an XLANG schedule in the Tracking database.

Important

  • Records are logged in the dta_wf_EventData and dta_wf_WorkFlowEvent tables only if the WorkFlowAuditClient application is started. To start the WorkFlowAuditClient application, you must complete the three steps listed in this topic. If WorkFlowAuditClient is stopped, no records are logged in the dta_wf_EventData and dta_wf_WorkFlowEvent tables.

After you complete these steps, records are logged in the dta_wf_EventData and dta_wf_WorkFlowEvent tables for messages that are exchanged between BizTalk Orchestration Services and BizTalk Messaging Services. The value logged in the nvcName field in the dta_wf_EventData table serves as a link between the dta_wf_EventData and dta_wf_WorkFlowEvent tables and the dta_interchange_details table, a core table in the Tracking database. For more information about the core tables, see Metadata Core Table Structure.

Messages sent from BizTalk Orchestration Services to BizTalk Messaging Services

All messages that are sent from BizTalk Orchestration Services to BizTalk Messaging Services by using the BizTalk Messaging port implementation in BizTalk Orchestration Designer are identified by a globally unique identifier (GUID) called the correlation identifier (correlationID). When a message is submitted from BizTalk Orchestration Services to BizTalk Messaging Services, the correlationID is logged in the uidSubmissionGUID field in the dta_interchange_details table. In addition, records are logged in the dta_wf_EventData and dta_wf_WorkFlowEvent tables. This enables you to use BizTalk Document Tracking to view the action events related to messages processed by an XLANG schedule.

Documents sent from BizTalk Messaging Services to BizTalk Orchestration Services

All documents that are submitted to BizTalk Messaging Services are identified by a GUID called the submission handle (SubmissionHandle). For more information about the submission handle, see Submit Method. When the document is sent from BizTalk Messaging Services to BizTalk Orchestration Services, the submission handle is recorded in the uidSubmissionGUID field in the dta_interchange_details table. In addition, when a document is sent from BizTalk Messaging Services to BizTalk Orchestration Services, the following two events occur:

  • The submission handle is inserted into the correlationID property of the document that is sent to BizTalk Orchestration Services.

  • Records are logged in the dta_wf_EventData and dta_wf_WorkFlowEvent tables. Because the document is sent from BizTalk Messaging Services, the submission handle is logged as the correlationID in the nvcName field in the dta_wf_EventData table.

Viewing action events

To use BizTalk Document Tracking to view action events related to messages processed by an XLANG schedule, you must create a query in BizTalk Document Tracking and then click the XLANG schedule icon. For more information about how to create queries and view XLANG schedule events, see Use Queries to Search and Sort Interchange and Document Data.

The dta_wf_EventData table

The following table contains one record for each property logged in relation to a monitored COM+ event that is generated by an XLANG schedule. Sets of multiple rows in this table share a common parent in the dta_wf_WorkFlowEvent table.

Field name | Description
nEventDataId | Integer key field that is incremented automatically.
nWorkFlowEventId | Foreign key to the parent event record in dta_wf_EventData.
nvcName | Correlation identifier (correlationID).
nvcValue | Any value. This is usually based on a GUID.

The dta_wf_WorkFlowEvent table

The following table is the parent table to dta_wf_EventData and contains one record for each monitored COM+ event that is generated by an XLANG schedule.

Field name | Description
nWorkFlowEventId | Integer key field that is incremented automatically.
nvcEventId | Type of event.
nvcEventName | Name of the event.
nProcessId | Process identifier for the originating event.
nvcApplicationId | XLANG schedule identifier.
nvcInstanceId | Identifier for the particular instance of the schedule.
nEventTime | Coordinated universal time (UTC) of the event as seconds elapsed since midnight, January 1, 1970.
nEventSubTime | Microseconds added to the ITime argument for time to a microsecond solution.
nEventTick | Value of the high-resolution performance counter when the event originated.
nvcServerName | Server on which the event was detected.
dtDateEntered | Date of the event.

Related Topics

Integrating BizTalk Services

Metadata Core Table Structure

Submit Method

Understanding Integrated XLANG Schedule Status for an Interchange


Understanding How to Find Interchanges and Associated Documents

You can use BizTalk Document Tracking to view all interchanges and documents using the query parameters that you specify. To maximize your search results and to minimize load on the server, it is important to understand queries and how to use them. For example, if you create a query with very few parameters defined, the query might return thousands of interchange records. This places a high demand on your time and on the server's processing capabilities. This situation is compounded if more than one person is querying the database at the same time.

There are two levels of queries in BizTalk Server: queries and advanced queries. Queries include the most common criteria that are used to narrow query results. Advanced queries enable you to further define query results by using expressions to search for specific data.

The following topics are covered in this section:

  • Understanding Queries

  • Understanding Advanced Queries


Understanding Queries

The three standard query parameters included in BizTalk Document Tracking are date range and time zone, source and destination identifiers, and document type. You can find interchange and document records by defining one or more of these criteria in a query. For example, you can search for all document types in a specified date range or you can find interchanges and documents that are a certain document type and that match selected source and destination organizations.

Date range and time zone

The date and time listed in BizTalk Document Tracking specifies when the document was processed by BizTalk Server. You can specify any date range for your query. By default, BizTalk Document Tracking provides the previous seven business days as the date range. Unlike the Source Selection, Destination Selection, and Document Type Selection lists, BizTalk Document Tracking does not allow you to leave the date range blank to search for documents for any date and time.

You can also specify whether you want the date and time to display in local time or in coordinated universal time (UTC). Most often, you probably want to view interchanges and documents using local time. However, if you are working with someone who is in a different time zone and you need to create common criteria for defining when a document was sent or received, use UTC.

Note

  • Using long date and time formats might introduce truncations in BizTalk Document Tracking because the date and time selection control only supports short formats.

    If you encounter any issue with the date and time format, you can change the formats used by your computer in the Control Panel by clicking Regional Options.

Source and destination organization

You can search for interchanges and documents based on the source organization, the destination organization, or both. In addition, when you create a query you can filter for documents from one or more organizations or all organizations. You can also search for interchanges and documents that originate in an application associated with an organization. For example, if source organization A has a spreadsheet application that sends information to a database application in destination organization B, you can determine when the information was sent and received.

Document type

You can search for interchanges and documents that have a specific document type, such as a purchase order or an invoice. In a query, you can combine document type criteria with source and destination qualifiers to find interchanges and documents sent and received between you and your trading partners. This type of query can help you analyze the business relationship between you and your trading partners.

Sort control

There are six sort controls that determine in what order the columns on the Query Results page are sorted. The default sort order of a query is as follows:

  • Source organization name. The name of the source organization for the document.

  • Source application name. The name of the application in which the document originated.

  • Destination organization name. The name of the destination organization for the document.

  • Destination application name. The name of the application to which the document is being sent.

  • Document type. The type of the document.

  • Time processed. The time at which the document was processed by BizTalk Server.

The Group related interchanges check box configures the Query Results page to display incoming interchanges grouped with associated outgoing interchanges. Clear this check box if you do not want to view incoming interchanges with associated outgoing interchanges.

Related Topic

Understanding Advanced Queries


Understanding Advanced Queries

If you find that a query returns too many interchange and document records, you can refine your search by implementing query expressions. In the Advanced Queries dialog box, you can create a new query expression in the Advanced Query Builder or browse through a list of query expressions that you previously saved. The expressions are SQL statements formed by the creation of conditional clauses that you add to the query. You have the following options to help you create an advanced query:

  • Source selection. A list of the fields on which you want to search. In BizTalk Messaging Manager, if you configured a channel or document definition to track a custom field(s), the field(s) appears in the Source Selection list. If you have not configured BizTalk Messaging Manager to track any fields, only "<Custom Search>" appears in the Source Selection list. For more information about tracking specific fields, see Set document logging properties and Select specification fields in a channel.

  • Operators. A list of the available operators (such as >, <, =, contains, or does not contain).

  • Value. You can type a value in this box to indicate the boundary value for the advanced query.

  • AND/OR. A list that contains the grouping operators (AND and OR) that are used to combine search conditions.

  • Query. A list of the queries you created.

  • Logical grouping. A description of the combined search conditions that you created by using the AND and OR grouping operators. When you add clauses to a query, information about grouping operators appears in the Logical grouping box. For example, the Logical grouping box might display the following:

    1 AND 2 AND (3 OR 4)

    In this example, conditions 1 and 2 apply, and either condition 3 or 4 is combined with conditions 1 and 2.

Notes

  • You can have more than one query with the same name.

  • When tracking specification fields as an Integer, Real, Date, or Text data type, specification field names that exceed 79 characters are truncated.

    Track these specification fields as a Custom data type. By doing this, the field names are stored together with the field values in an SQL ntext column, which holds a maximum length of 2^30 - 1 (1,073,741,823) characters.

  • If you are unable to locate details and the receipt status for a document, in BizTalk Server Administration, the Enable document tracking check box might not be selected. If this check box is not selected, receipts cannot be correlated.

    To enable document logging, complete the following steps:

    1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and click BizTalk Server Administration.

    2. In BizTalk Server Administration, expand Microsoft BizTalk Server 2002, right-click the BizTalk Server group for which you want to change the document tracking settings, and then click Properties.

    3. On the Tracking tab, select the Enable document tracking check box.

    Select any other options that you want to use.

International Issue

  • Depending on the system locale, a numeric value in XML data might be misinterpreted by BizTalk Server when logged as an Integer tracking field in the Tracking database. For example, in a German locale, an XML Number value of 4.0 is logged as 40 in the Tracking database because the decimal point (.) is misinterpreted as the digit grouping symbol.

    There are two workarounds for this issue. First, if you know in advance that the element/attribute value stores a decimal number, you can change the XML element/attribute data type to Real (r4) or Double Real (r8). Second, you can configure the document definition or channel to log an element/attribute with a Number data type as Real instead of Integer.

Related Topic

Understanding Queries


Understanding Query Results

Query results are organized on the Query Results page in two levels, interchange records and document records. The highest level of organization is interchange records. An interchange record represents an interchange submitted to or transmitted from Microsoft BizTalk Server 2002. Interchange records are the parent records for document instance records and thus help to organize the document instance records in a meaningful way. For more information about what fields are included in an interchange record, see Understanding Interchange Record Results. Graphically, interchange records appear as rows of data fields with an expand indicator at the left end of each row.

If you click the expand indicator, the document instance record(s) appears. Graphically, the document instance record(s) also appears as a row of data fields. Usually, there is one document instance record per interchange record. However, if multiple document types are sent in a single interchange, there is a document record for each document type sent in the interchange. For more information about what fields are included in a document instance record, see Understanding Document-Instance Record Results.

The following topics are covered in this section:

  • Tracking Database Schema Basics

  • Understanding Interchange Record Results

  • Understanding Document-Instance Record Results

  • Understanding Receipt Results

  • Understanding Results for Failed Transmissions


Tracking Database Schema Basics

To understand what appears on the Query Results page, it is important to have a basic understanding of the Tracking database schema. There are three core tables in the Tracking database that store the metadata (such as source and destination organization identifiers, date, time, and document type) for every interchange and document processed by BizTalk Server. The database tables are:

  • dta_interchange_details

  • dta_indoc_details

  • dta_outdoc_details

dta_interchange_details

The dta_interchange_details table stores all the relevant data for interchanges and is the parent table of the dta_indoc_details table and the dta_outdoc_details table. One record is stored in the table for each interchange processed by BizTalk Server. The fields in interchange records on the Query Results page are populated with data from this table. A field in this table designates whether the interchange is incoming or outgoing. For example, if you receive an interchange, it is represented on the Query Results page as an incoming interchange record. If you send an interchange, it is represented on the Query Results page as an outgoing interchange record. For more information about the dta_interchange_details table, see Metadata Core Tables or Metadata Core Table Structure.

dta_indoc_details

The dta_indoc_details table stores all data for every document submitted to BizTalk Server. This table is linked to the dta_interchange_details table through a primary key. The fields in document instance records associated with incoming interchange records on the Query Results page are populated with data from this table. For example, if you send a document and you want to view the tracking information for that document on the Query Results page, you must first locate the appropriate outgoing interchange record. Then, expand the record and the document instance record appears. That document instance record is associated with the dta_indoc_details table and displays the data in the fields you configured to be tracked. For more information about the dta_indoc_details table, see Metadata Core Tables or Metadata Core Table Structure.

dta_outdoc_details

The dta_outdoc_details table stores all data for every document generated by BizTalk Server. There might be multiple records in the dta_outdoc_details table for every record in the dta_indoc_details table because multiple documents can be generated from a single submission. For example, a document submitted to BizTalk Server might be sent to a distribution list of 10 ports. In this case, a single record is logged in the dta_indoc_details table and 10 records are logged in the dta_outdoc_details table. Thus, one outgoing interchange record with an associated document instance record appears on the Query Results page. The fields in the document instance record are populated with data from the dta_outdoc_details table. For more information about the dta_outdoc_details table, see Metadata Core Tables or Metadata Core Table Structure.

Related Topics

How Interchanges and Documents Are Logged

Metadata Core Tables

Metadata Core Table Structure

Understanding Document-Instance Record Results

Understanding Interchange Record Results

Understanding Receipt Results

Understanding Results for Failed Transmissions

Understanding the Tracking Database Schema


Understanding Interchange Record Results

Based on the query parameters that you specify, one or more interchange records are returned if matches for your query criteria are found. An interchange record represents an interchange submitted to or transmitted from Microsoft BizTalk Server 2002.

An interchange contains the information shown in the following table.

Interchange column heading | Description
Data | Provides a link to view the interchange data in its native format.
Schedule Provides a link to the XLANG schedule status information for the individual interchange, if it is available. If there is no XLANG schedule status information associated with the interchange, the following message appears:

There is no XLANG schedule information available for this interchange.
Direction | Specifies whether the interchange is submitted to BizTalk Server (incoming) or sent from BizTalk Server (outgoing).
Error Specifies if there are any errors associated with the document.

Possible error messages are:

  • No error.

  • A custom component could not be called.

  • The interchange could not be parsed.

  • The specified channel does not exist.

  • The interchange could not be serialized.

  • The interchange could not be encoded.

  • The interchange could not be signed.

  • The interchange could not be encrypted.

  • The transmission attempt failed (a retry is pending).

  • The last transmission attempt failed.

  • The document could not be parsed.

  • The document could not be validated.

  • A valid channel could not be found.

  • The document could not be mapped.

  • A valid messaging port could not be found.

  • The document could not be serialized.
Source Organization | Specifies the name of the source organization.
Source Application | Specifies the application from which the document originated.
Destination Organization | Specifies the name of the destination organization.
Destination Application | Specifies the destination application for the document.
Document Type | Specifies the type of the document. If there is more than one document type in an interchange, "<Multiple>" appears in this field.
Document Count | Specifies the number of documents in the interchange.
Control ID | Specifies a unique control number for electronic data interchanges (EDI) or an identifier for BizTalk reliable messages.
Receipt Status | Specifies the receipt status. Possible values for receipt status are None, Pending, Overdue, Accepted, Accepted with errors, or Rejected.
Time Processed | Indicates the time at which the interchange was processed. The time is set when the document tracking records are created. Once the field is set, it is not updated.
Time Sent | Specifies the time at which the interchange was sent if the transmission was successful. If the transmission is not successful, it is null. For inbound transmissions, this field is always null.
Source ID Qualifier | Specifies the type of source organization qualifier. This is the qualifier that BizTalk Server uses internally.
Source Identifier | Specifies the source organization identifier value. This is the source identifier as denoted in the data and is used to route the document. This is different from Source ID Qualifier. For more information about routing, see How Routing Information Is Logged.
Destination ID Qualifier | Specifies the type of destination organization qualifier.
Destination Identifier | Specifies the destination organization identifier value. For more information about routing, see How Routing Information Is Logged.

Related Topics

Tracking Database Schema Basics

Understanding Document-Instance Record Results

Understanding How to Find Interchanges and Associated Documents


Understanding Document-Instance Record Results

Document instance records in an interchange appear as a row of fields that describe the document information.

The document-instance record results contain the information shown in the following table.

Document column heading | Description
Data | Provides a link to view the data that is contained in the document instance in its native and XML format.
Tracking ID | Indicates a tracking key based on a globally unique identifier (GUID).
Document type | Specifies the type of document. If there are multiple documents in an interchange, this field specifies the document type. There is never more than one document type in this field. Additional document types appear as separate document instance records.
Compliance | Indicates whether the document is valid. Possible values for compliance are Valid or Not valid.
Error Specifies whether there are any errors associated with the document. Possible error messages are:
  • No error.

  • A custom component could not be called.

  • The interchange could not be parsed.

  • The specified channel does not exist.

  • The interchange could not be serialized.

  • The interchange could not be encoded.

  • The interchange could not be signed.

  • The interchange could not be encrypted.

  • The transmission attempt failed (a retry is pending).

  • The last transmission attempt failed.

  • The document could not be parsed.

  • The document could not be validated.

  • A valid channel could not be found.

  • The document could not be mapped.

  • A valid messaging port could not be found.

  • The document could not be serialized.
Receipt | Provides a link to the receipt information.

The following fields apply only to outgoing documents.

Receipt Status | Specifies the receipt status. Possible values for receipt status are None, Pending, Overdue, Accepted, Accepted with errors, or Rejected.
Real 1, Real 2 | Specifies data that has been captured from the document content as a real number. There are two fields than can contain real numbers.
Integer 1, Integer 2 | Specifies data that has been captured from the document content as an integer value. There are two fields that can contain integers.
Date 1, Date 2 | Specifies data that has been captured from the document content as a date value. There are two fields that can contain dates.
String 1, String 2 | Specifies data that has been captured from the document content as a string value. There are two fields that can contain strings.
Custom Search | Indicates additional data that has been captured as a string value. The limit for this field is 2 GB.

Notes

  • To configure what information you want tracked in outgoing documents, see Select specification fields in a document definition or Select specification fields in a channel.

  • If you configure fields (such as integers, reals, strings, dates, or custom fields) in the document definition as optional, if you configure those fields to be tracked, and if these fields are not included in the submitted document instance, the fields do not appear in the query results. BizTalk Document Tracking does not generate an error or warning message to let you know that data is missing from optional fields.

  • When tracking specification fields as an Integer, Real, Date, or Text data type, specification field names that exceed 79 characters are truncated.

    Track these specification fields as a Custom data type. By doing this, the field names are stored together with the field values in an SQL ntext column, which holds a maximum length of 2^30 - 1 (1,073,741,823) characters.

International Issue

  • Depending on the system locale, a numeric value in XML data might be misinterpreted by BizTalk Server when logged as an Integer tracking field in the Tracking database. For example, in a German locale, an XML Number value of 4.0 is logged as 40 in the Tracking database because the decimal point (.) is misinterpreted as the digit grouping symbol.

    There are two workarounds for this issue. First, if you know in advance that the element/attribute value stores a decimal number, you can change the XML element/attribute data type to Real (r4) or Double Real (r8). Second, you can configure the document definition or channel to log an element/attribute with a Number data type as Real instead of Integer.

Related Topics

Select specification fields in a channel

Select specification fields in a document definition

Tracking Database Schema Basics

Understanding How to Find Interchanges and Associated Documents

Understanding Interchange Record Results


Understanding Receipt Results

The following illustration shows the receipt flow in BizTalk Document Tracking. In the illustration, Document 1 is first processed by BizTalk Server A and is flagged to expect a receipt (Document 1, Expect receipt flag set). Next, BizTalk Server B picks up the document through a receive function (Document 1, Generate receipt flag set), processes the document, and generates a receipt [Receipt for Document 1 (outgoing)]. BizTalk Server A then receives the receipt [Receipt for Document 1 (incoming)].

When you view the receipt for Document 1, Expect receipt flag set, you first locate the appropriate interchange record on the Query Results page that corresponds to Document 1, Expect receipt flag set. By clicking the Receipt icon in the Receipt field, a new Query Results page opens. It contains the interchange record that BizTalk Server A generated when it processed Document 1, Expect receipt flag set. By clicking the Data icon in the Data column, the data that appears is the actual contents of the receipt. In the previous illustration, this last step corresponds to Receipt for Document 1 (incoming).

When you view the receipt for Document 1, Generate receipt flag set, you must first locate the appropriate interchange record on the Query Results page that corresponds to Document 1, Generate receipt flag set. By clicking the Receipt icon in the Receipt field, a new Query Results page opens. It contains the interchange record that BizTalk Server B generated when it processed Document 1, Generate receipt flag set. Expand the interchange record to view the document instance details. By clicking the Data icon in the Data field, the data that appears is the actual contents of the receipt. In the previous illustration, this last step corresponds to Receipt for Document 1 (outgoing).

Notes

  • Sending and receiving receipts works only with parsers that can process receipts. For information about receipts, see Understanding Receipts.

  • Reliable messaging receipts are not displayed in the BizTalk Document Tracking user interface.

Related Topics

How Receipts Are Logged

Tracking Database Schema Basics


Understanding Results for Failed Transmissions

When a transmission fails, the failure is logged in the Tracking database. However, not all errors that are logged in the Tracking database appear in the BizTalk Document Tracking user interface. Errors appear in the user interface only if a record was logged in the dta_outdoc_details table. For more information about the core tables, see Tracking Database Schema Basics or Metadata Core Tables.

Note

  • The Tracking database does not log an interchange parsing error if the interchange trailer is incorrect in an EDI interchange. If an interchange contains a valid document, but the interchange trailer contains incorrect information, the parser recognizes this as a nonfatal error and submits the document to Microsoft BizTalk Server for processing. An error is logged in Event Viewer, but no error is logged in the Tracking database because the Tracking database does not differentiate between fatal errors and nonfatal errors.

The following table outlines possible error messages and whether records get logged into the various core tables in the Tracking database.

Error message | Records logged | Comments
No error | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | The appropriate fields are logged in the three core tables.
A custom component could not be called. | None | This error message appears only if you have a custom preprocessor associated with a receive function. No records are logged in the Tracking database.
The interchange could not be parsed. | dta_interchange_details (incoming) | The interchange and the data are logged if there is a parsing error.
The specified channel does not exist. | dta_indoc_details dta_interchange_details (incoming) | None.
The interchange could not be serialized. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | An empty record is logged in the dta_interchange_details (outgoing) table. If the interchange is resubmitted and it succeeds, the record is updated.
The interchange could not be encoded. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | None.
The interchange could not be signed. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | None.
The interchange could not be encrypted. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | None.
The transmission attempt failed (a retry is pending). | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | None.
The last transmission attempt failed. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | None.
The document could not be parsed. | dta_indoc_details dta_interchange_details (incoming) | None.
The document could not be validated. | dta_indoc_details dta_interchange_details (incoming) | None.
A valid channel could not be found. | dta_indoc_details dta_interchange_details (incoming) | None.
The document could not be mapped. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | The record in the dta_outdoc_details table records the logging error, and an empty record is logged in the dta_interchange_details (outgoing) table.
A valid messaging port could not be found. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | The record in the dta_outdoc_details table records a NoPort error, and an empty record is logged in the dta_interchange_details (outgoing) table.
The document could not be serialized. | dta_indoc_details dta_interchange_details (incoming) dta_interchange_details (outgoing) dta_outdoc_details | Records in the dta_indoc_details and dta_outdoc_details table contain the serialization error.

Related Topics

Configure tracking settings for a server group

Suspended queue

Tracking Database Schema Basics

Understanding the Tracking Database Schema


Understanding Integrated XLANG Schedule Status for an Interchange

You can track the status of related XLANG schedules in BizTalk Document Tracking. Actions in schedules on a server can be monitored and stored in the appropriate tables in the Tracking database with an identifier that correlates them to specific message instances. Storage schema in the Tracking database and correlation are part of Microsoft BizTalk Server 2002, but event subscription functionality is not implemented when you install BizTalk Server 2002. However, a sample for performing tracking integration is provided. After you install BizTalk Server, you can find the source code for this sample in the \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAudit folder. Additionally, the bin subfolder contains the dynamic-link library (WorkFlowAudit.dll), and the Docs subfolder contains the documentation (Readme.txt) for this sample. There is a sample client application located in \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAuditClient.


Why Perform BizTalk Document Tracking Tasks

This section provides a quick reference about why you perform specific Document Tracking tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Open BizTalk Document Tracking for the first time
 To view the progress of documents processed by Microsoft BizTalk Server 2002. You can create queries or advanced queries to extract essential information from the Tracking database in an easy-to-view format.
  • Add users to BizTalk Server Report Users group
 To view the BizTalk Document Tracking user interface and save Advanced Query expressions. You must be a member of the BizTalk Server Report Users group to do these tasks.
Maintain the Tracking Database:
  • Create an archive Tracking database
 To create a repository where old interchange and document instance records are inserted for safekeeping. Creating an archive Tracking database is the first of four procedures you must sequentially perform to install the utilities for maintaining the Tracking database.
  • Create the schema for the archive Tracking database
 To use the archive Tracking database, you must create its schema. Creating the schema for the archive Tracking database is the second of four procedures you must sequentially perform to install the utilities for maintaining the Tracking database.
  • Configure the Tracking Database for a SQL linked server
 To archive the Tracking database and link it to the archive Tracking database. You must configure both databases, provided they are both on different databases. Configuring the Tracking database is the third of four procedures you must sequentially perform to install the utilities for maintaining the Tracking database.
  • Install the stored procedures on the Tracking database
 To archive and/or delete old interchange and document instance records, you must install specific stored procedures on the Tracking database. Installing the stored procedures on the Tracking database is the last of four procedures you must sequentially perform to install the utilities for maintaining the Tracking database.
  • Tracking Database Archive/Delete Stored Procedure Usage
 To archive and/or delete old interchange and document instance records, you must use specific stored procedures on the Tracking database.
Use Queries to Search and Sort Interchange and Document Data:
  • Search by date for interchange and document information
 To use queries to locate, view, and save interchange and document instance records and associated data using standard search criteria, such as date.
  • Search by organization for interchange and document information
 To use queries to locate, view, and save interchange and document instance records and associated data using standard search criteria, such as source organization.
  • Search by document type for interchange and document information
 To use queries to locate, view, and save interchange and document instance records and associated data using standard search criteria, such as document information.
  • Search for interchange and document information by combining query parameters
 To combine the following query parameters in a single query session to locate, view, and save interchange and document instance records and associated data: source and destination selections, document type, and date and time.
  • Clear search criteria for organizations and document types
 To clear all search criteria and return to the default search for all source and destination organizations and all document types.
  • Customize the Query Results page
 To display and sort incoming interchanges grouped with associated outgoing interchanges.
  • View search parameters for the Query Results page
 To view the following search parameters and their associated values: Date Range, Time Zone, Expression Name, Sort Order, Organization Selection, and Document Type Selection.
Use Advanced Queries:
  • Build advanced queries
 To locate specific data, such as a document instance with a specific purchase order number.
  • Locate existing advanced queries
 To load and reuse existing advanced queries that you have previously created and saved.
  • Edit existing advanced queries
 To add, modify, or remove specific conditions to refine your document search.
  • Clear existing advanced queries
 To clear an existing advanced query, you must remove the current expression.
  • Delete existing advanced queries
 If you no longer need the pre-created advanced queries, you can select and delete them in order to maintain a shorter list of existing advanced queries.
Save Interchange, Document, and Custom Search Data:
  • Save interchange data
 To view the data offline. This helps you to troubleshoot certain situations or analyze your business practices.
  • Save document instance data
 To view the data offline. This helps you to troubleshoot certain situations or analyze your business practices.
  • Save custom-field search data
 To view the data offline. This helps you to troubleshoot certain situations or analyze your business practices.


How to Perform BizTalk Document Tracking Tasks

This section provides task-specific information that explains how to find, view, and save search results for interchange and document instance records and associated data. It is highly recommended that you review the About BizTalk Document Tracking section to fully understand the search capabilities and expected query results.

BizTalk Document Tracking has two levels of searching capability: query and advanced query. You can use queries when you want to locate documents using standard search criteria, such as source organization. You can use advanced queries when you want to locate specific data in documents, such as a Purchase Order Total.

The following procedures are covered in this section:

  • Open BizTalk Document Tracking for the first time

  • Open BizTalk Document Tracking

  • Add users to BizTalk Server Report Users group
  • Maintain the Tracking Database

  • Use Queries to Search and Sort Interchange and Document Data

  • Use Advanced Queries

  • Save Interchange, Document, and Custom Search Data


Open BizTalk Document Tracking for the first time

If you open BizTalk Document Tracking for the first time and if you do not have Windows Common Controls and the BizTalk Document Tracking control installed on your computer, you are prompted to install the components. If you have the components installed on your computer, see Open BizTalk Document Tracking.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Document Tracking.

    The Web Page Dialog dialog box appears to prompt you to install the following components:

    • Windows Common Controls

    • BizTalk Document Tracking Installation Control
  2. Click Continue to install the Windows Common Controls.

    The Security Warning dialog box appears.

  3. Click Yes to install the BizTalk Document Tracking Installation Control.

Note

  • A dialog box with the following message might appear during selection or query selection:

    This page accesses data on another domain. Do you want to allow this?

    To avoid this message in Internet Explorer, you can add a secure Web site to the Trusted sites zone on the Security tab of the Internet Options dialog box.

    To manually configure the settings on your browser to trust this Web application, add the Web application to the list of trusted sites in Internet Explorer. For more information about adding the Web application to the list of trusted sites, see Configure IIS settings for BizTalk Server 2002.

Related Topics

Configure IIS settings for BizTalk Server 2002

Open BizTalk Document Tracking


Open BizTalk Document Tracking

  • On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Document Tracking.

    —Or—

    If you created a favorite in Microsoft Internet Explorer, you can open BizTalk Document Tracking from Internet Explorer.

Note

  • A dialog box with the following message might appear during selection or query selection:

    This page accesses data on another domain. Do you want to allow this?

    To avoid this message in Internet Explorer, you can add a secure Web site to the Trusted sites zone on the Security tab of the Internet Options dialog box.

    To manually configure the settings on your browser to trust this Web application, add the Web application to the list of trusted sites in Internet Explorer. For more information about adding the Web application to the list of trusted sites, see Configure IIS settings for BizTalk Server 2002.

Related Topics

Configure IIS settings for BizTalk Server 2002

Open BizTalk Document Tracking for the first time


Add users to BizTalk Server Report Users group

To view the BizTalk Document Tracking user interface and to save Advanced Query expressions, you must be a member of the BizTalk Server Report Users group. In addition, your user login account needs to be added to the SQL Server login account and given public, db_owner, and dta_ui_role roles on the Tracking database (InterchangeDTA). For more information about setting SQL Server login accounts and establishing database permissions, see SQL Server and BizTalk Server 2002 Database Interactions.

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

  2. Expand System Tools, expand Local Users and Groups, and then click the Groups folder.

  3. In the details pane, click BizTalk Server Report Users.

  4. On the Action menu, point to All Tasks, and then click Add to Group.

    The BizTalk Server Report Users Properties dialog box appears.

  5. Click Add.

  6. In the Look in list, click your domain or computer name.

  7. In the list that contains the users and computers associated with the domain or computer you selected in step 6, click the user account to add, click Add, and then click OK.

  8. Click OK to close the BizTalk Server Report Users Properties dialog box.


Maintain the Tracking Database

Utilities are included in BizTalk Server to maintain the Tracking database. When you install BizTalk Server, the appropriate files are copied to the \Program Files\Microsoft BizTalk Server\Setup folder. However, to activate the utilities, you must follow the instructions in this section.

Note

  • If you do not track interchanges and documents in your BizTalk Server installation, or if you do not want to use the SQL scripts included in BizTalk Server to archive and purge your Tracking database, you do not need to perform the procedures in this section.

To install the utilities to maintain the Tracking database, you must complete the following procedures in the order listed.

The following procedures are covered in this section:

  • Create an archive Tracking database

  • Create the schema for the archive Tracking database

  • Configure the Tracking database for a SQL linked server

  • Install the stored procedures on the Tracking database
  • Tracking Database Archive/Delete Stored Procedure Usage

Important

  • If you are unable to complete the following procedures, verify that the user account you are using to connect to the server running Microsoft® SQL Server™ has sufficient permissions to create stored procedures and SQL Server Agent jobs.

  • The default name of the Tracking database is InterchangeDTA. If the name of your Tracking database is different, then you must change all instances of the string InterchangeDTA in the BTS_Tracking_Archive_Purge_Script.sql script to the name of your Tracking database.

Notes

  • To avoid unnecessary disk space allocation, it is recommended that you enable the Truncate log on checkpoint option. For more information about how to configure this option, see Avoid unnecessary disk space allocation.

  • For more information about the stored procedures that maintain the Tracking database utility, see Tracking Database Archive/Delete Stored Procedure Usage.


Create an archive Tracking database

Perform the following steps on the server that you want to host the archive Tracking database.

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and click Enterprise Manager.

  2. Expand Microsoft SQL Servers, expand SQL Server Group, and click the server on which you want to create an archive Tracking database.

  3. On the Action menu, point to New and click Database.

  4. In the Database Properties dialog box, type a name for the archive Tracking database and click OK.


Create the schema for the archive Tracking database

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and click Query Analyzer.

  2. In the SQL Server list, click the name of the SQL Server that hosts the archive Tracking database that you created in Create an archive Tracking database, enter the appropriate login information, and click OK.

  3. If you have Microsoft SQL Server 7.0 installed, in the DB list, click the name of the archive Tracking database and continue to step 5.

    —Or—

    If you have Microsoft SQL Server 2000 installed, on the Query menu, click Change Database.

  4. Click the name of the archive Tracking database and click OK.

  5. On the File menu, click Open.

  6. In the Open Query File dialog box, in the Look in list, browse to \Program Files\Microsoft BizTalk Server\Setup.

  7. Click BTS_Tracking_ArchiveDB_Schema.sql and click Open.

  8. On the Query menu, click Execute.


Configure the Tracking database for a SQL linked server

Perform the following steps on the SQL Server that hosts the Tracking database.

  1. Verify that Query Analyzer is open.

  2. On the File menu, click Disconnect.

  3. On the File menu, click Connect.

  4. In the SQL Server list, click the name of the SQL Server that hosts the Tracking database that you want to archive, enter the appropriate login information, and click OK.

  5. If you have SQL Server 7.0 installed, in the DB list, click the name of the Tracking database that you want to archive and continue to step 7.

    For example: InterchangeDTA

    —Or—

    If you have SQL Server 2000 installed, on the Query menu, click Change Database.

  6. Click the name of the Tracking database and click OK.

    For example: InterchangeDTA

    Note

    • Be sure to select the Tracking database and not the archive Tracking database.
  7. Configure the archive Tracking database as an SQL linked server.

    The following example is a sample SQL statement for configuring a linked server. In this example, a remote database server called "Seattle2" is a linked server on the local SQL Server:

    EXEC sp_addlinkedserver N'Seattle2',
 N'SQL Server'
  8. If necessary, configure a mapping between the logins for the local and remote linked SQL Servers.

    The following example is a sample SQL statement to create a mapping between the system administrator (sa) login on the local and remote linked SQL Servers. This sample assumes that the remote sa login password is "abc123."

    EXEC sp_addlinkedsrvlogin '<Name of remote SQL Server>',
 'FALSE', 'sa', 'sa', 'abc123'

Important

  • If both your Tracking database and archive Tracking database are on the same SQL Server, you do not need to set up linked servers. If the databases are set up on separate SQL Servers, it is important to configure your Tracking database and your archive Tracking database as linked servers. In this instance, linked servers must be set up for the dta_purge_old_records stored procedure to archive (INSERT) old records into the remote archive Tracking database. If you only want to purge records, then linking servers is not required.

  • The default name of the Tracking database is InterchangeDTA. If the name of your Tracking database is different, then you must change all instances of the string InterchangeDTA in the BTS_Tracking_Archive_Purge_Script.sql script to the name of your Tracking database.

Note

  • If the system administrator account does not have a password, an empty string ('') must be used. For security reasons, this configuration is not recommended.


Install the stored procedures on the Tracking database

Perform the following steps on the SQL Server that hosts the Tracking database. This should be the same server that you configured in the previous procedure.

  1. Verify that Query Analyzer is open.

  2. On the File menu, click Open.

  3. In the Open Query File dialog box, in the Look in list, browse to \Program Files\Microsoft BizTalk Server\Setup.

  4. Click BTS_Tracking_Archive_Purge_Script.sql and click Open.

  5. On the Query menu, click Execute.

    The script creates a stored procedure named dta_purge_old_records. The script creates a SQL Server Agent job named "Archive and Purge BizTalk Tracking database: <Name of your Tracking database>." By default, the SQL Server Agent job is not enabled.

  6. If necessary, open Enterprise Manager.

  7. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server that hosts the Tracking database, expand Management, expand SQL Server Agent, and then click Jobs.

  8. In the details pane, click Archive and Purge BizTalk Tracking Database: <Name of your Tracking database>.

  9. On the Action menu, click Properties.

  10. On the Steps tab, verify that dtaStep_execute_stored_proc is selected and click Edit.

  11. In the Edit Job Step dialog box, on the General tab, set the input parameters in the Command box.

    The following are some examples for configuring the input parameters passed to the dta_purge_old_records stored procedure. For more information about the syntax and arguments in this stored procedure, see Tracking Database Archive/Delete Stored Procedure Usage.

    • To delete but not archive all completely processed interchanges and documents that are older than one day, edit the job as follows:
      USE InterchangeDTA
EXEC dta_purge_old_records 1, 24, 1,0
    • To archive and delete all interchanges regardless of whether they are completely processed, with the exception of the latest 1,000 interchanges, edit the job as follows:
      USE InterchangeDTA
EXEC dta_purge_old_records 2, 1000, 0, 1,
 N'<Name of a SQL Server>',
 N'<Name of the archive Tracking database>'
  12. Click OK.

  13. On the Schedules tab, verify that BizTalk Archive and Purge Schedule is selected and click Edit.

  14. In the Edit Job Schedule dialog box, click Change in the Schedule Type box.

  15. In the Edit Recurring Job Schedule dialog box, change the occurrence, frequency, and duration of the SQL Server Agent job to what you want and click OK.

  16. On the General tab, select the Enabled check box and click OK.

    The changes are saved and the SQL Server Agent job is enabled.

Note

  • This procedure assumes that the installation folder for BizTalk Server 2002 is \Program Files\Microsoft BizTalk Server. If you installed BizTalk Server 2002 in a different folder, your folder paths might be different from the folder paths listed here.


Tracking Database Archive/Delete Stored Procedure Usage

This topic describes the syntax and arguments in the Tracking database SQL scripts.

Syntax

The following code is the syntax used in the dta_purge_old_records stored procedure:

[ @nPurgeType = ] nPurgeType,
[ @nPurgeValue = ] nPurgeValue,
[ @nCompletedInterchangesOnly = ] nCompletedInterchangesOnly,
[ @nArchiveFlag = ] nArchiveFlag
[ , [ @nvcArchiveDBServer = ] N'nvcArchiveDBServer' ]
[ , [ @nvcArchiveDBName = ] N'nvcArchiveDBName' ]

Arguments

The following are the arguments used in the syntax:

[ @nPurgeType = ] nPurgeType

The [ @nPurgeType = ] nPurgeType argument is an integer value that indicates whether to select the interchanges for deleting by timestamp or by row count. If nPurgeType is 1, then records are deleted by timestamp. If nPurgeType is 2, then records are deleted by row count.

[ @nPurgeValue = ] nPurgeValue

The [ @nPurgeValue = ] nPurgeValue argument is an integer value. The meaning of this argument depends on the value of nPurgeType.

If the value of nPurgeType is 1, then nPurgeValue represents the number of hours to subtract from CURRENT_TIMESTAMP to determine how to archive interchanges older than a certain date and time. For example, if you specify 96 as nPurgeValue, then you archive interchanges that are older than 96 hours (four days).

If the value of nPurgeType is 2, then nPurgeValue represents the number of interchanges to be left in the database after records are archived and deleted from the database. For example, specifying 25,000 results in archiving all interchanges below the top 25,000 rows.

[ @nCompletedInterchangesOnly = ] nCompletedInterchangesOnly

The [ @nCompletedInterchangesOnly = ] nCompletedInterchangesOnly argument is an integer value that configures whether or not interchanges that require additional processing are deleted from the database. For example, some interchanges or documents might be waiting for an acknowledgement or might have to be resubmitted.

If you configure nCompletedInterchangesOnly to equal 0, then the purge job deletes interchanges and documents whether or not they still require additional processing. Setting this argument to 0 results in faster completion of the purge job because there is less filtering.

If you configure nCompletedInterchangesOnly to equal 1, then the purge job does not delete interchanges and documents that require additional processing. Setting this argument to 1 results in slower completion of the purge job because there is more filtering.

[ @nArchiveFlag = ] nArchiveFlag

The [ @nArchiveFlag = ] nArchiveFlag argument is an integer value that indicates whether the stored procedure archives interchange and document records before deleting them. If the value of nArchiveFlag is 0, then the stored procedure does not archive any interchange or document records. If the value of nArchiveFlag is 1, then the stored procedure archives the interchange and document records before they are deleted from the database.

[ @nvcArchiveDBServer = ] nvcArchiveDBServer

The [ @nvcArchiveDBServer = ] nvcArchiveDBServer argument is an optional argument. Configure this argument if you configure nArchiveFlag to equal 1. This argument is an nvarchar(128) data type and it specifies the name of the database server where the stored procedure archives the interchange and document records.

[ @nvcArchiveDBName = ] nvcArchiveDBName

The [ @nvcArchiveDBName = ] nvcArchiveDBName argument is an optional argument. Configure this argument if you configure nArchiveFlag to equal 1. This argument is an nvarchar(128) data type and it specifies the name of the database where the stored procedure archives the interchange and document records.


Use Queries to Search and Sort Interchange and Document Data

You can use queries to locate, view, and save interchange and document instance records and associated data using standard search criteria, such as document type or source organization.

The following procedures are covered in this section:

  • Search by date for interchange and document information

  • Search by organization for interchange and document information

  • Search by document type for interchange and document information

  • Search for interchange and document information by combining query parameters

  • Clear search criteria for organizations and document types

  • Customize the Query Results page

  • View search parameters for the Query Results page

Notes

  • When you select your query parameters, be as specific as possible. This reduces load on the server and the amount of time it takes to return your query results.

  • A dialog box with the following message might appear during selection or query selection:

    This page accesses data on another domain. Do you want to allow this?

    To avoid this message in Internet Explorer, you can add a secure Web site to the Trusted sites zone on the Security tab of the Internet Options dialog box.

    To manually configure the settings on your browser to trust this Web application, add the Web application to the list of trusted sites in Internet Explorer. For more information about adding the Web application to the list of trusted sites, see Configure IIS settings for BizTalk Server 2002.

  • If you configure a nonstandard format for dates, numbers, time, currency, and so on in Regional Options in the Control Panel, you might not be able to save a new query or view advanced queries that you saved. For more information, see Use Advanced Queries.

    To view existing advanced queries, only choose options available in the lists in Regional Options. For example, on the Date tab, in the Short date format list, choose options in the list. Do not type or cut and paste other formats in the Short date format list.


Search by date for interchange and document information

  1. In BizTalk Document Tracking, in the Date Range area, in the Display dates in list, click Local Time or UTC to specify the time zone of the display dates.

  2. In the From date list, type the beginning date for the period that you want to track, or click the arrow to display a calendar from which you can select a date.

    To change the time, type the beginning time in the list next to the From date list, or click the up or down arrow.

  3. In the To date list, type the end date for the period that you want to track, or click the arrow to display a calendar from which you can select a date.

    To change the time, type the end time in the list next to the To date list, or click the up or down arrow.

  4. Click the Query button.

    The Query Results page appears.

  5. To view interchange data, locate the interchange record that contains the data you want to view and, in the Data column, click its respective Data icon.

    The View Interchange Data page appears.

  6. To view the XLANG schedule status for an interchange, in the Schedule column, click a Schedule icon.

    The View Schedule Summary page appears.

  7. To view a document instance record associated with an interchange, click the expand indicator (+) next to the interchange that contains the document instance record you want to view.

  8. To view the data associated with a document instance, in the Data field, click its respective Data icon.

    The View Document Instance Data page appears.

  9. To view the data in its native format or XML format, click View native format or View XML format.

  10. To view the receipt data associated with a document instance, in the Receipt field, click the Receipt icon.

    A new Query Results page appears.

  11. Click the expand indicator (+) next to the interchange and then click the Data icon in the Data field.

  12. To view the custom-search field data for a document instance, locate the document for which you want to view the custom-search field data, use the horizontal scroll bar to display the Custom Search field, and then click the Custom Search icon.

    The View Custom Search Field page appears.

Notes

  • The value you select in the Display dates in list controls the search times and the display results. For example, if you select UTC in the Display dates in list and you specify 0800 in the time field, you search for all data processed on or after 0800 hours in coordinated universal time (UTC). This is not the same as 0800 Local Time.

  • The default date setting is seven days prior to the current date.

  • The display dates are the BizTalk Server–generated timestamps on the metadata for the document instances and interchanges. They are not dates for the actual document content. To locate documents based on the actual document date, create an Advanced Query expression. For more information about advanced queries, see Build advanced queries.

  • If you specify only a date range in a query, BizTalk Document Tracking searches for all source and destination organizations and all document types. This single search parameter is not recommended. For best results, always create a query with very specific parameters to limit the number of interchange records returned on the Query Results page.

  • The XLANG schedule status is the last detected event, processed start time, processed end time, and so on.

  • If you have Microsoft Internet Explorer 5 installed on your computer, when you view document instance data, the pointer might appear as an hourglass instead of an arrow or a pipe. If this happens, you can still select View native format or View XML format or click the Save As and Close buttons. If you upgrade to Microsoft Internet Explorer 5.5, the pointer appears as an arrow or a pipe.

Related Topics

Build advanced queries

Search by document type for interchange and document information

Search by organization for interchange and document information

Search for interchange and document information by combining query parameters

Understanding Document-Instance Record Results

Understanding Interchange Record Results

Understanding Queries


Search by organization for interchange and document information

  1. In BizTalk Document Tracking, in the Source Selection list, click the organization(s) for which you want to view interchanges and documents. To select an application that is associated with a source organization, click the expand indicator (+) next to the organization, and then click the application(s) you want. To select all source organizations, click Select All.

    —Or—

    In BizTalk Document Tracking, in the Destination Selection list, click the organization(s) for which you want to view interchanges and documents. To select an application that is associated with a destination organization, click the expand indicator (+) next to the organization, and then click the application(s) you want. To select all destination organizations, click Select All.

    You can choose organizations and applications in the Source Selection and Destination Selection lists for the same query.

  2. Click the Query button.

    The Query Results page appears. Any interchanges that match your query criteria are listed here.

  3. To view interchange data, locate the interchange record that contains the data you want to view and, in the Data column, click the Data icon.

    The View Interchange Data page appears.

  4. To view the XLANG schedule status for an interchange, in the Schedule column, click a Schedule icon.

    The View Schedule Summary page appears.

  5. To view a document instance record associated with an interchange, click the expand indicator (+) next to the interchange that contains the document instance records you want to view.

  6. To view the data associated with a document instance, in the Data field, click the Data icon.

    The View Document Instance Data page appears.

  7. To view the data in its native format or XML format, click View native format or View XML format.

  8. To view the receipt data associated with a document instance, in the Receipt field, click the Receipt icon.

    A new Query Results page appears.

  9. Click the expand indicator (+) next to the interchange and, in the Data field, click the Data icon.

  10. To view the custom-search field data for a document instance, locate the document for which you want to view the custom-search field data, use the horizontal scroll bar to display the Custom Search field, and then click the Custom Search icon.

    The View Custom Search Field page appears.

Notes

  • If you do not select specific source and destination organizations, the query returns interchange and document records for all source and destination organizations. The options Clear All and Select All generate the same results on the Query Results page. For best results, always create a query with very specific parameters to limit the number of interchange records generated on the Query Results page.

  • The XLANG schedule status is the last detected event, processed start time, processed end time, and so on.

  • If you have Microsoft Internet Explorer 5 installed on your computer, when you view document instance data, the pointer might appear as an hourglass instead of an arrow or a pipe. If this happens, you can still select View native format or View XML format or click the Save As and Close buttons. If you upgrade to Microsoft Internet Explorer 5.5, the pointer appears as an arrow or a pipe.

Related Topics

Search by date for interchange and document information

Search by document type for interchange and document information

Search for interchange and document information by combining query parameters

Understanding Document-Instance Record Results

Understanding Interchange Record Results

Understanding Queries


Search by document type for interchange and document information

  1. In BizTalk Document Tracking, in the Document Type Selection area, click Show Documents.

  2. In the Document Type Selection list, click the document type(s) that you want to find. To select all document types, click Select All.

  3. Click the Query button.

    The Query Results page appears.

  4. To view interchange data, locate the interchange record that contains the data you want to view and, in the Data column, click the Data icon.

    The View Interchange Data page appears.

  5. To view the XLANG schedule status for an interchange, in the Schedule column, click a Schedule icon.

    The View Schedule Summary page appears.

  6. To view a document instance record associated with an interchange, click the expand indicator (+) next to the interchange that contains the document instance records you want to view.

  7. To view the data associated with a document instance, in the Data field, click the Data icon.

    The View Document Instance Data page appears.

  8. To view the data in its native format or XML format, click View native format or View XML format.

  9. To view the receipt data associated with a document instance, in the Receipt field, click the Receipt icon.

    A new Query Results page appears.

  10. Click the expand indicator (+) next to the interchange and, in the Data field, click the Data icon.

  11. To view the custom-search field data for a document instance, locate the document for which you want to view the custom-search field data, use the horizontal scroll bar to display the Custom Search field, and then click the Custom Search icon.

    The View Custom Search Field page appears.

Notes

  • If you do not select one or more document types to narrow your search, the query returns all document types in the list. For best results, always create a query with very specific parameters to limit the number of interchange records generated on the Query Results page.

  • The XLANG schedule status is the last detected event, processed start time, processed end time, and so on.

  • If you have Microsoft Internet Explorer 5 installed on your computer, when you view document instance data, the pointer might appear as an hourglass instead of an arrow or a pipe. If this happens, you can still select View native format or View XML format or click the Save As and Close buttons. If you upgrade to Microsoft Internet Explorer 5.5, the pointer appears as an arrow or a pipe.

Related Topics

Search by date for interchange and document information

Search by organization for interchange and document information

Search for interchange and document information by combining query parameters

Understanding Document-Instance Record Results

Understanding Interchange Record Results

Understanding Queries


Search for interchange and document information by combining query parameters

  1. In BizTalk Document Tracking, you can combine any of the following query parameters in a single query session to find and view interchange and document instance records and associated data:
    • Source selection. For more information about creating queries using the source selection parameter, see Search by organization for interchange and document information.

    • Destination selection. For more information about creating queries using the destination selection parameter, see Search by organization for interchange and document information.

    • Document type. For more information about creating queries using the document type parameter, see Search by document type for interchange and document information.

    • Date and time. For more information about creating queries using date and time parameters, see Search by date for interchange and document information.
  2. Click the Query button.


Clear search criteria for organizations and document types

  • In BizTalk Document Tracking, click Clear All beneath the Source Selection, the Destination Selection, or the Document Type Selection list.

Note

  • When you click Clear All, BizTalk Document Tracking returns to the default search for all source and destination organizations and for all document types. For best results, always create a query with very specific parameters to limit the number of interchange records returned on the Query Results page.


Customize the Query Results page

  1. In BizTalk Document Tracking, in the Sort Control area, select the Group related interchanges check box.

    This step configures the Query Results page to display incoming interchanges grouped with associated outgoing interchanges. Clear this check box if you do not want to view incoming interchanges with associated outgoing interchanges.

  2. In the Sort Control area, in the Sort order 1 list, click the first sort order option that you want to use. Repeat this step for each sort order list to configure the sort order of your documents on the Query Results page.

    Each Sort order list contains the following options:

    • Source Organization Name

    • Source Application Name

    • Destination Organization Name

    • Destination Application Name

    • Document Type

    • Time Processed


View search parameters for the Query Results page

  1. Define parameters for a query, and then click the Query button.

    The Query Results page appears.

    For more information about how to create queries or advanced queries, see:

    • Search by date for interchange and document information

    • Search by organization for interchange and document information

    • Search by document type for interchange and document information

    • Build advanced queries
  2. On the Search Parameters bar, click the Show icon.

    The following search parameters and associated values are listed in the Search Parameters area:

    • Date Range

    • Time Zone

    • Expression Name

    • Sort Order

    • Source Selection

    • Destination Selection

    • Document Type Selection

Related Topics

Build advanced queries

Search by date for interchange and document information

Search by document type for interchange and document information

Search by organization for interchange and document information


Use Advanced Queries

If you need to locate specific data, such as a document instance with a specific purchase order number, you can use an advanced query to locate the information.

The following procedures are covered in this section:

  • Build advanced queries

  • Locate existing advanced queries

  • Edit existing advanced queries

  • Clear existing advanced queries

  • Delete existing advanced queries

Notes

  • If you configure a nonstandard format for dates, numbers, time, currency, and so on in Regional Options in Control Panel, you might not be able to save a new query or view advanced queries that you saved. For more information, see Use Advanced Queries.

    To view existing advanced queries, only choose options available in the lists in Regional Options. For example, on the Date tab, in the Short date format list, choose options in the list. Do not type or cut and paste other formats in the Short date format list.

  • The float and real data types are known as approximate data types. The behavior of float and real data types follows the IEEE 754 specification on approximate numeric data types. Approximate numeric data types do not store the exact values specified for many numbers; rather, they store an extremely close approximation of the value. For many applications, the small difference between the specified value and the stored approximation is not noticeable. At times, though, the difference is evident. Because of this approximate nature of the float and real data types, do not use these data types when exact numeric behavior is required, such as in financial applications, in operations involving rounding, or in equality checks. Instead, use the integer, decimal, money, or smallmoney data types.

  • BizTalk Server allows the Number data type to be tracked as an Integer data type. If the value of the number in the document exceeds the size of the Integer data type, a warning message appears. This warning message contains the value that could not be tracked.

    Do not exceed the size of the Integer data type when tracking a Number data type as an Integer.

International Issue

  • Depending on the system locale, a numeric value in XML data might be misinterpreted by BizTalk Server when logged as an Integer tracking field in the Tracking database. For example, in a German locale, an XML Number value of 4.0 is logged as 40 in the Tracking database because the decimal point (.) is misinterpreted as the digit grouping symbol.

    There are two workarounds for this issue. First, if you know in advance that the element/attribute value stores a decimal number, you can change the XML element/attribute data type to Real (r4) or Double Real (r8). Second, you can configure the document definition or channel to log an element/attribute with a Number data type as Real instead of Integer.


Build advanced queries

  1. In BizTalk Document Tracking, in the Advanced Query area, click New.

    The Advanced Query Builder page appears.

  2. In the Source selection list, click an option to specify your source selection criteria.

    This is the name of the captured field for which you are searching.

  3. In the Operators list, click an operator.

  4. In the Value box, type a value.

  5. In the AND/OR list, click either AND or OR to combine or compare this condition with another condition. This step is optional.

  6. Click Done.

  7. Repeat steps 2 through 6 until you add all conditions you want.

  8. Perform one of the following procedures:
    • Click OK to limit the use of this expression to the current query session.

    • Click Save to save the expression for future query sessions. In the BizTalk Document Tracking dialog box, type the expression name in the Enter the expression name box (limit the expression name to 50 characters), and then click OK.

Caution

  • Make sure you select unique, case-sensitive names for your queries. New records for the Tracking field are not created if a case-insensitive comparison matches an existing entry and the data type. Although you can enter queries with the same name in BizTalk Document Tracking, the only way to differentiate them is to open each query, thus minimizing their usefulness.

  • Always enter the custom fields exactly as they appear in the document being tracked.

Notes

  • The collection of one or more conditions in an advanced query is called an expression.

  • If you have the focus on the Source Selection list and you click a button, you might need to click the button a second time to activate it.

  • In BizTalk Messaging Manager, if you configured a channel or document definition to track custom field(s), those fields appear in the Source Selection list. If you have not configured BizTalk Messaging Manager to track any fields, only "<Custom Search>" appears in the Source Selection list. For more information about tracking specific fields, see Set document logging properties and Select specification fields in a channel.

  • When you track interchanges or documents using custom search fields and you query on a value, only those interchanges or documents tracked from the custom search fields appear on the Query Results page.

Related Topics

Clear existing advanced queries

Delete existing advanced queries

Edit existing advanced queries

Locate existing advanced queries


Locate existing advanced queries

  1. In BizTalk Document Tracking, in the Advanced Query area, click Browse.

    The Advanced Queries dialog box appears.

  2. Select an existing query and click OK.

Note

  • If you have the focus on the Source Selection list and you click a button, you might need to click the button a second time to activate it.

Related Topics

Build advanced queries

Clear existing advanced queries

Delete existing advanced queries

Edit existing advanced queries


Edit existing advanced queries

  1. In BizTalk Document Tracking, in the Advanced Query area, click Browse.

    The Advanced Queries dialog box appears.

  2. Select an existing query to edit and click Edit.

    The Advanced Query Builder dialog box appears.

  3. Perform one or more of the following procedures:
    • Click New to add an additional condition. Specify conditions for each of the four fields, and then click Done.

    • Click an existing condition, click Edit, modify any of the four fields, and then click Done.

    • Select an existing condition and click Remove.
  4. Click Save.

    The Advanced Queries dialog box appears.

  5. Select the query you just edited, and then click OK.

Note

  • If you have the focus on the Source Selection list and you click a button, you might need to click the button a second time to activate it.

Related Topics

Build advanced queries

Clear existing advanced queries

Delete existing advanced queries

Locate existing advanced queries


Clear existing advanced queries

  • In BizTalk Document Tracking, in the Advanced Query area, click Clear to remove the current expression from the Expression name box.

Note

  • If you click the Refresh button in Internet Explorer, the advanced query is not cleared from the Expression name box.

Related Topics

Build advanced queries

Delete existing advanced queries

Edit existing advanced queries

Locate existing advanced queries


Delete existing advanced queries

  1. In BizTalk Document Tracking, in the Advanced Query area, click Browse.

    The Advanced Queries page appears.

  2. Select a query and click Delete.

  3. Close the Advanced Queries dialog box when you are finished.

Note

  • If you have the focus on the Source Selection list and you click a button, you might need to click the button a second time to activate it.

Related Topics

Build advanced queries

Clear existing advanced queries from a query

Edit existing advanced queries

Locate existing advanced queries


Save Interchange, Document, and Custom Search Data

If you configured BizTalk Messaging Manager, the BizTalk Messaging Configuration object model, and/or BizTalk Server Administration to store incoming and outgoing interchanges and their documents, you can save interchanges, document data, and custom-field search data so you can view them offline. This helps you to troubleshoot certain situations or analyze your business practices.

The following procedures are covered in this section:

  • Save interchange data

  • Save document instance data

  • Save custom-field search data


Save interchange data

  1. Define parameters for a query and click the Query button.

    The Query Results page appears.

    For more information about how to create queries or advanced queries, see:

    • Search by date for interchange and document information

    • Search by organization for interchange and document information

    • Search by document type for interchange and document information

    • Build advanced queries
  2. Locate the interchange record that contains the interchange data you want to save and, in the Data field, click the Data icon.

    The View Interchange Data page appears.

  3. Click Save As.

  4. In the File name box, type a name for the file, and then click Save.

Related Topics

Build advanced queries

Save custom-field search data

Save document instance data

Search by date for interchange and document information

Search by document type for interchange and document information

Search by organization for interchange and document information


Save document instance data

  1. Define parameters for a query and click the Query button.

    The Query Results page appears.

    For more information about how to create queries or advanced queries, see:

    • Search by date for interchange and document information

    • Search by organization for interchange and document information

    • Search by document type for interchange and document information

    • Build advanced queries
  2. Locate the interchange record that contains the document instance data you want to save and click the expand indicator (+) to the left of the interchange.

  3. In the Data field, click the Data icon.

    The View Document Data page appears.

  4. Click Save As.

  5. In the File name box, type a name and an extension (either the .xml file extension or the native file extension of the document) for the file, and then click Save.

Related Topics

Build advanced queries

Save custom-field search data

Save interchange data

Search by date for interchange and document information

Search by document type for interchange and document information

Search by organization for interchange and document information


Save custom-field search data

  1. Define parameters for a query and click the Query button.

    The Query Results page appears.

    For more information about how to create queries or advanced queries, see:

    • Search by date for interchange and document information

    • Search by organization for interchange and document information

    • Search by document type for interchange and document information

    • Build advanced queries
  2. Click the expand indicator (+) to the left of the interchange record that contains the document you want to view.

  3. Use the horizontal scroll bar to display the Custom Search field for the document you want to view and click the Custom Search icon.

    The View Custom Search Field page appears.

  4. Click Save As.

  5. In the File name box, type a name for the file, and then click Save.

Related Topics

Build advanced queries

Save document instance data

Save interchange data

Search by date for interchange and document information

Search by document type for interchange and document information

Search by organization for interchange and document information


Troubleshooting BizTalk Document Tracking

This section provides general information about BizTalk Document Tracking troubleshooting.

The following topics are covered in this section:

  • Problem displaying BizTalk Document Tracking user interface

  • Interchanges are not stored

  • Documents are not stored

  • Nothing is displayed in the query results

  • Tracking fields are not displayed in the query results

  • Too many search arguments


Problem displaying BizTalk Document Tracking user interface

Cause: Microsoft Office Web Components are not installed.

Solution: Install Microsoft Office Web Components.

  1. Click Start, point to Settings, and then click Control Panel.

  2. Double-click Add/Remove Programs.

    The Add/Remove Programs dialog box appears.

  3. Click Microsoft Office 2000 SR-1 Premium.

  4. Click Change.

  5. Click Add or Remove Features.

  6. Click the expand indicator (+) next to Office Tools.

  7. Click Office Web Components and click the option appropriate for your installation.

  8. Click Update Now.


Interchanges are not stored

Cause: Tracking is turned off in BizTalk Server Administration.

Solution: Turn on tracking in BizTalk Server Administration.

  1. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server 2002 and click the server group for which documents are not being stored.

  3. On the Action menu, click Properties.

    The BizTalk Server Group Properties dialog box appears.

  4. Click the Tracking tab.

  5. Select the Enable document tracking check box.

  6. Select one or more of the following options:
    • Log incoming interchange

    • Log outgoing interchange

    • Log the original MIME-encoded message
  7. Click OK.

Related Topic

Configure tracking properties for a server group


Documents are not stored

Cause: Document logging properties have not been set properly in Channel configurations in BizTalk Messaging Manager.

Solution: Turn on the appropriate document logging options in Channel configurations.

  1. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. On the Document Logging page of the Channel Wizard, in the Log inbound document area, select the appropriate check boxes:

  3. In native format. Stores inbound documents for the channel in the original format. This is the default setting.

  4. In XML format. Stores inbound documents for the channel in XML format.

  5. In the Log outbound document area, select the appropriate check boxes:

  6. In native format. Stores outbound documents for the channel in the original format.

  7. In XML format. Stores outbound documents for the channel in XML format.

  8. If you are creating a new channel, click Next. For instructions about completing the next step, go to Create Channels.

  9. If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit Channels.

  10. If you have completed your changes, click Finish.


Nothing is displayed in the query results

Cause one: The date and time range is incorrect.

Solution: Check that the date and time range is correct. For example, if you sent a document in the past 5 minutes and the time range is set to look for documents in the past 10 minutes or greater, your document will not appear in the query results.

Cause two: The data might have been removed from the database.

Solution: Contact your Database Administrator for more information.

Related Topic

Search by date for interchange and document information


Tracking fields are not displayed in the query results

Cause: BizTalk Server could not convert the data or there is an arithmetic overflow error.

Solution: Look for the following error message in the Event Log:

<path and file name>: The following tracking field for submission <globally unique identifier> could not be logged:

Tracking field: <name of field>

Specification field name: <name of specification field>/DTADataTypeTest/String/@_String

Actual value: <actual value of field>

Check and correct the Tracking field settings in the document or channel configuration.

Related Topics

Select specification fields in a channel

Set document logging properties


Too many search arguments

Cause: You specified too many options in the Source Selection and/or Destination Selection list.

Solution: Make your query as specific as possible. Reduce the number of options selected in the Source Selection and/or Destination Selection list and click Query.

Related Topic

Use Queries to Search and Sort Interchange and Document Data


Monitoring Documents

You can use Windows Management Instrumentation (WMI) and Microsoft Operations Manager (MOM) 2000 to monitor Microsoft® BizTalk™ Server 2002. These two management tools enable you to:

  • Monitor standard and custom alert notifications.

  • Consume and use Microsoft Windows NT® Event Log entries for BizTalk Server, with help from the tool guidelines.

  • Create performance statistics for the XLANG Scheduler without the use of scripts.

  • Monitor the basic BizTalk Server components, such as the BizTalk Server databases and database tables, per-instance queues, and services.

The following topics are covered in this section:

  • About Windows Management Instrumentation

  • About Microsoft Operations Manager


About Windows Management Instrumentation

Windows Management Instrumentation (WMI) is a data-management layer that is included in Microsoft® Windows® 2000. Microsoft BizTalk Server 2002 uses the WMI layer to encapsulate administrative functions. When you use BizTalk Server Administration to change group, server, and queue settings, the new values are stored in the BizTalk Messaging Management database through the BizTalk Server WMI provider. In BizTalk Server 2002, this WMI provider uses a Microsoft SQL Server™ database to store administrative objects. WMI supports a uniform scripting application programming interface (API) that gives applications and scripts access to the WMI provider on a local computer or a remote computer. For more information and samples for using WMI, see BizTalk Managing and Monitoring.

Notes

  • WMI has a restriction on syntax and valid characters for a WMI object path. The following are a list of invalid characters:

    ~` ! @ # $ % ^ & * ( ) + = [ ] { } | ;\" '< > , . ?

    Do not use any of these characters when you create a server group name.

  • All timestamps are created using the local time on SQL Server. However, the WMI provider refers to all timestamps in coordinated universal time (UTC). The administration console then converts the timestamps back to local time for display.

  • To access the WMI database layer programmatically, you can use the InterchangeProvSchema.mof file located in the \Program Files\Microsoft BizTalk Server\Setup folder. This file contains the WMI classes corresponding to the Administration objects. For more information about WMI Application Programming, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "WMI Application Programming."

  • To execute WMI queries through Microsoft Operations Manager (MOM), you need to be a member of the BizTalk Server Administrators group on the server on which the query will be executed. You also need to authorize the BizTalk Server Administrators group with all the permissions to the root/MicrosoftBizTalkServer WMI namespace of the server. For more information about authorizing users in WMI, see Windows 2000 Help and Grant WMI namespace permission to a Windows account.

The following topics are covered in this section:

  • Custom Counters Overview

  • Suspended Queue Overview

Related Topics

BizTalk Managing and Monitoring

Windows Management Instrumentation


Custom Counters Overview

Custom counters provide a programmatic way to define custom-built Windows Management Instrumentation (WMI) class instances based on an advanced query of the Tracking database. These queries can be constructed based on the following fixed set of attributes:

  • Time range

  • Document source

  • Document destination

  • Document type

These attributes can be specified using regular expressions. Each query returns a count of the documents matching the criteria, and you can specify how the query results will be sorted. In addition, you can specify a set of criteria (a query) as a new class instance that can be consumed by Microsoft Operations Manager (MOM), thus enabling alerts to be set as part of a MOM rule.

WMI classes enable you to:

  • Create a new instance of a WMI class that defines a specific tracking query.

  • For document source and document destination, validate the tracking query created in the new WMI class instance.

  • Execute the query defined in the new WMI class instance to acquire the number of documents in the Tracking database matching this query.

For more information, see Custom Counters.

Related Topics

Creating a Custom Counter Using WMI

Custom Counter Query Properties

Validating the Custom Counter


Suspended Queue Overview

The Suspended queue contains work items that have not been successfully processed for a variety of reasons, including parsing errors, serialization errors, failed transmissions, or the inability to find a channel configuration. You can view and retrieve documents from the Suspended queue either through the BizTalk Server Administration console or programmatically through the BizTalk Server Windows Management Instrumentation (WMI) provider. WMI queries can be constructed based on the following fixed set of attributes:

  • Destination

  • Source

  • Document name

  • State

  • Channel handle

  • Port handle

  • String suspended GUID

  • Reason

For more information about viewing the Suspended queue through the Administration console, see Suspended Queue. For more information about viewing the Suspended queue through the WMI provider, see Accessing the Suspended Queue.

Related Topics

Accessing the Suspended Queue

MicrosoftBizTalkServer_SuspendedQueue

Suspended Queue Monitoring


About Microsoft Operations Manager

Microsoft Operations Manager (MOM) 2000 is a set of event collection, performance monitoring, and reporting tools for Microsoft server operating systems and server-based applications. MOM centrally monitors, manages, and secures a wide range of resources, improving the availability, performance, and security of Windows 2000 networks and applications by providing proactive, real-time system monitoring. MOM enables you to quickly identify potentially serious network problems, track resolution progress, and provide resolution information that others in your organization can use.

MOM also enables you to monitor the performance of your network using Windows Management Instrumentation (WMI). You can track performance thresholds and collect sampled data for trend analysis. You can create and view graphs of sampled data, and use the information for capacity planning.

MOM provides the following features:

  • Event-driven operations monitoring

  • Self-deploying, scalable solutions

  • Advanced security policy enforcement and auditing capabilities

  • Improved system availability and performance tracking

  • Numerous ways to view and report data

  • Increases reliability and availability

MOM consumes various data from servers running BizTalk Server including Performance Counters, WMI Counters and Events, and Windows NT Events. MOM consumes this data through the creation of providers, server groups, and rules. Providers are simply individual sources of data, and are defined by naming the data source (that is, the type), the individual provider name, and various other attributes specific to the data source. For example, the provider for monitoring the queue size, in bytes, for a queue named "myQueue" is as follows:

Provider = Windows NT Performance Counter – MSMQ Queue-Bytes in Queue-myQueue-15.0-Minutes

Note

  • The sampling rate is part of the provider definition for the Windows NT Performance Counter data source.

Once providers are created, rules that process data from the providers can be created. Rules are contained in one of the three Processing Rules Groups within MOM:

  • Event Processing Rules. These rules can process different events that occur on a server and, based on an event, can take a specified action. Examples of events are instances in the Windows NT Event Log, other standard log files like the Internet Information Services (IIS) W3C log files created by the IIS service, and WMI events. Examples of actions are raising an Alert, sending an e-mail, and running a script.

  • Performance Processing Rules. These rules process performance or capacity type counters. Performance rules can be measuring rules or threshold rules. While measuring rules only collect statistics for reporting, the threshold rules can raise alerts. This is true even if the measuring and threshold rules have exactly the same provider.

  • Alert Processing Rules. Event and performance rules are not used to respond to alerts directly, rather, separate alert rules are created to actually respond to the alerts raised by event and performance rules. An Alert Processing Rule enables you to associate one global response to a large set of alerts that have something in common.

International Issue

  • Microsoft Operations Manager (MOM) 2000 is available in English only. The following list identifies supported scenarios and limitations when using MOM with Microsoft BizTalk Server 2002:
    • Managed BizTalk Servers can be English or Japanese languages.

    • MOM servers can be English or Japanese, but must be in a single language.

    • MOM uses Microsoft SQL Server 2000. The SQL Server installation for the MOM server can be English or Japanese.

    • The Web console is not supported in non-English configurations. However, the Microsoft Management Console (MMC) console is supported in non-English configurations.

    • MOM setup supports English only. All domain and computer names must be English.

    • MOM does not support mixed-language environments. The MOM infrastructure servers all need to have the same language operating system as the monitored computers. The exception is that when monitoring French or German systems, it is required that all the MOM infrastructure servers be English. This is because BizTalk Server does not support English MOM running on French or German localized infrastructure servers. BizTalk Server does not support English MOM infrastructure servers with Japanese managed computers.

    • On all property pages, the single-line edit fields cannot display double-byte characters, such as Japanese characters, because of a font issue. The missing information can be found in the description field in the right pane or in the multi-line edit fields.

For more detailed information about MOM, see Microsoft Operations Manager Help.

The following topic is covered in this section:

  • BizTalk Server 2002 Enterprise Edition Management Pack

Notes

  • MOM can be installed on a computer running BizTalk Server or on an independent computer dedicated to monitoring your system.

  • MOM is not included on the BizTalk Server 2002 CD. It must be obtained independently. For more information about MOM, go to the Microsoft Operations Manager Web site (www.microsoft.com/mom/).

  • To execute WMI queries through MOM, you need to be a member of the BizTalk Server Administrators group on the server on which the query will be executed.

Related Topic

About Windows Management Instrumentation


BizTalk Server 2002 Enterprise Edition Management Pack

To further strengthen the monitoring capabilities of Microsoft Operations Manager (MOM), the BizTalk Server 2002 Enterprise Edition Management Pack module contains computer grouping and processing rules, as well as other information that enables you to monitor events specific to BizTalk Server 2002. You can import the BizTalk Server 2002 Management Pack to monitor computers in the current configuration group.

The BizTalk Server 2002 Management Pack provides an initial set of rules and counters that include all of the Messaging and Orchestration error messages, the BizTalk Server databases, Windows NT events, and queues. You can customize the Management Pack to reflect your monitoring needs and obtain greater detail in the areas your organization is interested in monitoring.

The BizTalk Server 2002 Management Pack provides over 900 rules of various types including:

  • A processing event rule for every Windows Application event that can be generated from BizTalk Messaging and BizTalk Orchestration.

  • Performance measurement rules for performance counters and database file sizes in BizTalk Server 2002. These support the 20 performance views in the Management Pack specific to BizTalk Server.

  • Performance threshold rules for performance counters and database file sizes in BizTalk Server 2002 (one for error severity and one for warning severity).

  • Custom Counter, Suspended Queue, and three other sample rules that show how to build rules customized to your specific BizTalk Server 2002 implementation.

Using these rules, system administrators can be notified about:

  • When the BizTalk Messaging Service is down or how long it has been running.

  • When any Windows event is generated from BizTalk Messaging or BizTalk Orchestration.

  • Whether documents to an important customer are being suspended and how many documents to an important customer are successfully sent per period of time.

  • When the BizTalk Server databases are getting too large.

  • When the number of failed schedules per unit time becomes too large.

The following procedure and topics are covered in this section:

  • Configuring MOM to Monitor BizTalk Server 2002

  • Import the BizTalk Server 2002 Management Pack

  • Notification Groups

  • View

  • Fully Configured Rules

  • User-Defined Rules

Note

  • MOM 2000 must be installed prior to importing the BizTalk Server 2002 Enterprise Edition Management Pack.


Configuring MOM to Monitor BizTalk Server 2002

The following steps provide guidelines of what needs to be done to set up Microsoft Operations Manager (MOM) to start monitoring your BizTalk Server 2002 computers. The detailed steps are documented in Microsoft Operations Manager Help.

  1. Install MOM 2000 on the computer that will be used for monitoring your BizTalk Server configuration. For more information, see the Microsoft Operations Manager Installation Guide, located in the Documentation folder of the MOM installation CD.

    Note

    • The Consolidator/Agent Manager domain account required by MOM must have Windows Administrator privileges on each BizTalk Server computer you plan to monitor, including the servers that host the SQL Server databases used by BizTalk Server. You can achieve this by adding the account to the Windows Administrators group on each server, or by adding the account to a domain group that is a member of the local Administrators group (for example, the Domain Administrators group).
  2. Import the BizTalk Server 2002 Enterprise Edition Management Pack into MOM. For more information, see Import the BizTalk Server 2002 Management Pack and, in Microsoft Operations Manager Help, see on "Importing a Management Pack Module."

    Notes

    • The BizTalk Server 2002 Enterprise Edition Management Pack can be found in the MOM folder on the BizTalk Server 2002 installation CD.

    • When importing the BizTalk Server 2002 Management Pack, MOM provides three behavioral options:

      Merge, and retain changes that my company has made to rules.

      Merge, and always use the rules defined in the Management Pack. Preserve my company's knowledge base comments.

      Replace existing rule groups with those of the imported Management Pack.

      When importing the BizTalk Server Management Pack for the first time, you can select any option. However, for subsequent imports it is important to select the option that corresponds to the behavior you want.

    • The BizTalk Server 2002 Enterprise Edition Management Pack contains a computer group called Microsoft BizTalk Server 2002 Enterprise Edition. This group contains all computers managed by MOM that contain the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk Server\1.0.
  3. Once MOM is successfully installed, designate the group of computers that you want MOM to monitor and/or periodically poll to discover new BizTalk Server installations. For more information, see "Understanding Agents", "Install Agents", "Configuring Agent Manager Properties", "Configuring Agent Deployment", and "Agent Managers Window" in Microsoft Operations Manager Help.

    Note

    • By setting up managed computer rules and scanning for computers that match those rules (as described in the MOM documentation previously referenced), you specify to MOM the set of computers that you want to monitor. This set should include all of the BizTalk Server 2002 servers and associated SQL Servers that you want to monitor. This will install a local service called One Point that runs as LocalSystem.
  4. To verify that the rules you have specified actually include the computers you intended, perform the following steps:
    1. Verify that MOM has performed a computer scan since the last time the managed computer rules were modified. The most effective way to verify this is to actually invoke the scan manually. For more information, see "Scanning Managed Computers" in Microsoft Operations Manager Help.

      Caution

      If the managed computer rules you have defined for your Agent Manager result in a large number of matching computers, the scan could take longer than you want.

    2. Check the list of managed computers. For instructions on how to view this list, see "Viewing the Managed Computers List for an Agent Manager" in Microsoft Operations Manager Help.
  5. Configure the Microsoft BizTalk Server 2002 Enterprise Edition computer group to include any separate servers that host SQL Server databases used by BizTalk Server but do not have BizTalk Server 2002 installed. For more information, see "Excluding or Including Computers in a Computer Group" in Microsoft Operations Manager Help.

    Note

    • The BizTalk Server 2002 Enterprise Edition Management Pack creates a computer group called Microsoft BizTalk Server 2002 Enterprise Edition. This group contains all computers managed by MOM that contain the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk Server\1.0. If there are separate servers that host SQL Server databases used by BizTalk Server but do not have BizTalk Server 2002 installed, these servers must be specifically added to the computer group by name.

After completing each of the steps successfully, MOM is fully configured to monitor BizTalk Server 2002. To verify that all of the computers you intend to monitor have been successfully added to the BizTalk Server 2002 Enterprise Edition computer group, follow these steps:

  1. On the Start menu, point to Programs, point to Microsoft Operations Manager, and then click MOM Administration Console.

    The MOM Administration Console appears.

  2. Double-click the Microsoft Operations Manager tree node, double-click Monitor, and then click All Computer Groups.

  3. In the right pane, double-click Microsoft BizTalk Server 2002 Enterprise Edition.

  4. All of the computers currently determined by MOM to be in this computer group are listed.

    Note

    • It might take several minutes or longer for MOM to discover all of the computers for the group. If, after a reasonable time period (depending on the number of computers scanned and other factors), the computers you intended to monitor do not appear in the computer group, check the rules for your Agent Manager and computer group to make sure you have included the computers you want.


Import the BizTalk Server 2002 Management Pack

To monitor your BizTalk Server system, you must import the BizTalk Server 2002 Management Pack to the computer where Microsoft Operations Manager (MOM) is installed.

  1. On the Start menu, point to Programs, point to Microsoft Operations Manager, and then click MOM Administrator Console.

  2. In the left pane, expand Microsoft Operations Manager (default), expand Rules, and then click Processing Rule Groups.

  3. On the Action menu, click Import Management Pack.

    The Import Management Pack dialog box appears.

  4. In the Management Pack area, browse to the Microsoft BizTalk Server 2002 CD, browse to the MOM folder, and select BizTalk2002.akm.

  5. Click Open.

  6. Click Import.

Notes

  • The BizTalk Server 2002 Management Pack is included on the BizTalk Server 2002 CD. However, MOM must be installed before the BizTalk Server 2002 Management Pack can be used. For more information about MOM, go to the Microsoft Operations Manager Web site (www.microsoft.com/mom/).

  • For more information about installing MOM, see Microsoft Operations Manager Help.


Notification Groups

A notification group in Microsoft Operations Manager (MOM) is a defined role to which a notification configuration is applied. Configuration for a notification group consists of defining the mechanisms (for example, e-mail, paging, and instant messaging) that members of that role will be notified on, and the specific members of each role. When alert rules are created and notifications defined, notification groups are specified as the target of the alert notifications.

Clearly, you will want to define your own notification groups, however, Microsoft Operations Manager provides out-of-the-box the following notification groups:

  • IT Administrators. This includes the group of operations and IT management professionals who have responsibility for keeping systems running at a technical level.

  • Database Administrators. This is a special group of IT administrators who have particular responsibilities and skills to maintain databases.

  • Business Administrators. This group represents the individuals who understand the business processes implemented on top of the technology and who have responsibility for monitoring the behavior of the system on a business level.

Note

  • For the rules to function, it is necessary to add an Operator/User to the notification groups. For more information, see "Adding an Operator to a Notification Group" in Microsoft Operations Manager Help.


View

To monitor the overall health of your system and to facilitate maintenance tasks, the Views in Microsoft Operations Manager (MOM) enable you to display specific information from the database. These views are updated every 15 minutes. The BizTalk Server 2002 Management Pack offers views related to the following performance counters included in the Management Pack:

  • Activated Schedule Instances

  • Asynchronous Submissions

  • Completed Schedule Instances

  • Database File Size: BTM

  • Database File Size: DTA

  • Database File Size: SQ

  • Database File Size: XLANG

  • Database Log Size: BTM

  • Database Log Size: DTA

  • Database Log Size: SQ

  • Database Log Size: XLANG

  • Dehydrated Schedule Instances

  • Documents Processed

  • Documents Received

  • Failed Schedule Instances

  • Interchanges Received

  • Items Suspended

  • Messaging Uptime

  • Synchronous Submissions

  • Transactions Aborted

For a description of these counters, see Performance Counters.

Microsoft Operations Manager (MOM) provides two ways to display the views:

  • The default view presents a list of the performance counters and providers that have views associated with them.

  • The graphical view enables you to see the performance of your system by plotting the selected performance counter or provider over time, showing the value of the counter and/or rule for the last two hours and updating the values every 15 minutes.

For more information about the default views available in MOM and how to create additional views, see Microsoft Operations Manager Help.

The following procedure is covered in this section:

  • Access BizTalk Server views


Access BizTalk Server views

  1. On the Start menu, point to Programs, point to Microsoft Operations Manager, and then click MOM Administrator Console.

  2. In the left pane, expand Microsoft Operations Manager (default), expand Monitor, expand Public Views, expand Microsoft BizTalk Server, and then expand Microsoft BizTalk Server 2002 Enterprise Edition.

  3. Click the view you want to access.

For more information about using views in MOM, see Microsoft Operations Manager Help.


Fully Configured Rules

To further enhance the monitoring capabilities of Microsoft Operations Manager (MOM), the BizTalk Server 2002 Management Pack includes basic rules that are fully configured out-of-the-box for all the Windows NT application events specific to BizTalk Server and for the BizTalk Server performance counters.

The following topics are covered in this section:

  • Windows NT Event Rules

  • Performance Counters

Related Topic

User-Defined Rules


Windows NT Event Rules

One of the fully configured rule types included in the BizTalk Server 2002 Management Pack is the Windows NT Event Log Monitoring rule type. All the Windows NT application events specific to BizTalk Server are imported as basic rules to Microsoft Operations Manager (MOM). The monitored Windows NT events are categorized as one of the following rules:

  • Needs to raise an alert and/or requires an individual response.

  • An event to be used as a filter.

  • An event to be consolidated with other similar events.

In the MOM console tree, these rules will be distributed among the three types of MOM rules under the Microsoft BizTalk Server 2002 node:

  • Event Processing Rules

  • Alert Processing Rules

  • Performance Processing Rules

For more information about MOM rules, see Microsoft Operations Manager Help.

Event ID

Usually, each error message that appears in the Event Log has a unique error ID. However, sometimes error messages are related to each other. For example, a login error might cause access to the BizTalk Messaging Management database to fail, which in turn creates a cascade of error messages because the receive functions cannot submit messages. In these cases, for messaging errors, BizTalk Server produces only one error log that summarizes the errors under one event ID. When looking at the description of the error in the Event Log, you will see that all the cascaded error messages are listed, with the individual event ID being the first thing in the entry.

Microsoft Operations Manager (MOM) uses the event ID of each individual error message within the event description to identify each error message uniquely.

Note

  • Summarized error logs are created only for messaging errors. For orchestration, each error is logged independently in the Event Log, whether it is due to a previous error or not.

Related Topic

Windows NT Event Rules

Copyright © 1999–2001 Microsoft Corporation.
All rights reserved.

Did you find this information useful? Please send your suggestions and comments about the documentation to BizTalk Server Documentation Feedback@microsoft.com


Performance Counters

The BizTalk Server 2002 Management Pack contains providers and rules for the following performance counters:

  • Messaging. These performance counters monitor BizTalk Messaging Services events.

  • XLANG. These performance counters monitor BizTalk Orchestration Services events.

Performance counter values are collected on a regular basis by means of measuring rules. A measuring rule is a type of performance rule that specifies the collection of a numeric value from a performance counter.

The following tables list the performance counters and provide a brief description of each.

Messaging performance counters

Performance counter | Description
Asynchronous Submissions | Integer representing the number of submit calls completed since the last time the BizTalk Messaging Service was started.
Documents Processed | Integer representing the number of documents processed, that is, pulled from the Work queue and sent to a port destination address, since the last time the BizTalk Messaging Service was started.
Documents Received | Integer representing the total number of documents that have been received by BizTalk Server. This includes all documents that make it into the Work queue and any that have failed.
Interchanges Received | Integer representing the number of interchanges received by the messaging engine.
Items Suspended | Integer representing the number of items suspended in the Suspended queue.
Messaging Uptime | Integer representing the time the BizTalk Messaging Service has been running since the last time it was started.
Synchronous Submissions | Integer representing the number of synchronous submissions.

XLANG performance counters

Performance counter | Description
Activated Schedule Instances | Integer representing the number of activated schedule instances since the last time the XLANG COM+ processes were started.
Completed Schedule Instances | Integer representing the number of XLANG schedule instances that have completed successfully since the last time the XLANG COM+ processes were started for a specified server.
Dehydrated Schedule Instances | Integer representing the total number of dehydrated schedule instances.
Failed Schedule Instances | Integer representing the number of XLANG schedule instances that have failed for a specified server.
Transactions Aborted | Integer representing the number of transactions aborted for the XLANG COM+ processes since the last time the processes were started.

Note

  • All the XLANG performance counters are cumulative counts of all the XLANG processes on a specified server.

Database performance counters

Rule counter | Description
Database File Size: BTM | Size of the data files, in kilobytes, in the BizTalk Messaging Management database. This counter is used to create a related view.
Database File Size - Error: BTM | Size of the data files, in kilobytes, in the BizTalk Messaging Management database. This counter is used to generate an error response.
Database File Size - Warning: BTM | Size of the data files, in kilobytes, in the BizTalk Messaging Management database. This counter is used to generate a warning response.
Database File Size: SQ | Size of the data files, in kilobytes, in the BizTalk Server Shared Queue database. This counter is used to create a related view.
Database File Size - Error: SQ | Size of the data files, in kilobytes, in the BizTalk Server Shared Queue database. This counter is used to generate an error response.
Database File Size - Warning: SQ | Size of the data files, in kilobytes, in the BizTalk Server Shared Queue database. This counter is used to generate a warning response.
Database File Size: DTA | Size of the data files, in kilobytes, in the BizTalk Server Tracking database. This counter is used to create a related view.
Database File Size - Error: DTA | Size of the data files, in kilobytes, in the BizTalk Server Tracking database. This counter is used to generate an error response.
Database File Size - Warning: DTA | Size of the data files, in kilobytes, in the BizTalk Server Tracking database. This counter is used to generate a warning response.
Database File Size: XLANG | Size of the data files, in kilobytes, in the Orchestration Persistence database. This counter is used to create a related view.
Database File Size - Error: XLANG | Size of the data files, in kilobytes, in the Orchestration Persistence database. This counter is used to generate an error response.
Database File Size - Warning: XLANG | Size of the data files, in kilobytes, in the Orchestration Persistence database. This counter is used to generate a warning response.
Database Log Size: BTM | Size of the log files, in kilobytes, for the BizTalk Messaging Management database. This counter is used to create a related view.
Database Log Size - Error: BTM | Size of the log files, in kilobytes, for the BizTalk Messaging Management database. This counter is used to generate an error response.
Database Log Size - Warning: BTM | Size of the log files, in kilobytes, for the BizTalk Messaging Management database. This counter is used to generate a warning response.
Database Log Size: SQ | Size of the log files, in kilobytes, for the BizTalk Server Shared Queue database. This counter is used to create a related view.
Database Log Size - Error: SQ | Size of the log files, in kilobytes, for the BizTalk Server Shared Queue database. This counter is used to generate an error response.
Database Log Size - Warning: SQ | Size of the log files, in kilobytes, for the BizTalk Server Shared Queue database. This counter is used to generate a warning response.
Database Log Size: DTA | Size of the log files, in kilobytes, for the BizTalk Server Tracking database. This counter is used to create a related view.
Database Log Size - Error: DTA | Size of the log files, in kilobytes, for the BizTalk Server Tracking database. This counter is used to generate an error response.
Database Log Size - Warning: DTA | Size of the log files, in kilobytes, for the BizTalk Server Tracking database. This counter is used to generate a warning response.
Database Log Size: XLANG | Size of the log files, in kilobytes, for the Orchestration Persistence database. This counter is used to create a related view.
Database Log Size - Error: XLANG | Size of the log files, in kilobytes, for the Orchestration Persistence database. This counter is used to generate an error response.
Database Log Size - Warning: XLANG | Size of the log files, in kilobytes, for the Orchestration Persistence database. This counter is used to generate a warning response.

Note

  • During BizTalk Server 2002 installation, the BizTalk Messaging Management database object name defaults to InterchangeBTM; the Tracking database object name defaults to InterchangeDTA; the Shared Queue database object name defaults to InterchangeSQ and the Orchestration Persistence database object name defaults to XLANG. If you have renamed these default database object names you will need to modify the database performance counters to make sure they point to the correct databases.
Rule counter | Description
Suspended Queue Size (Measure) | Size of the BizTalk Server Suspended queue at a given point in time. This counter is used to generate a warning response.

Related Topics

Fully Configured Rules

User-Defined Rules


User-Defined Rules

Although the BizTalk Server 2002 Management Pack provides a comprehensive set of fully configured rules to monitor BizTalk Server 2002, you might want to monitor events that are specific to your system configuration, which the BizTalk Server 2002 Management Pack does not provide. In these cases, you can create your own user-defined rules. The Suspended Queue Monitoring sample provides information about how to create user-defined rules for BizTalk Server monitoring.

For more information about creating user-defined rules, see Microsoft Operations Manager Help.

Related Topics

Fully Configured Rules

Suspended Queue Monitoring


BizTalk Server 2002 Application Development

Microsoft® BizTalk™ Server 2002 provides tools and services that enable you to create executable applications for controlling your business processes and the exchange of data between trading partners and applications within your business.

The following topics are covered in this section:

  • BizTalk SEED Wizard

  • Deploying BizTalk Server Resource Applications

  • Designing BizTalk Orchestrations

  • Configuring BizTalk Messaging Services

  • Creating Specifications and Mapping Data

  • Integrating BizTalk Services


BizTalk SEED Wizard

The BizTalk SEED Wizard enables companies to package their Microsoft® BizTalk™ Server 2002 configurations into a SEED package and make it available to trading partners through the Internet. Companies that create a SEED package still have to manually configure BizTalk Server to receive documents. However by creating a SEED package, trading partners are able to configure BizTalk Server, test their configuration, and begin exchanging documents with the initiating company. A SEED package helps companies rapidly start conducting business with partners. A SEED package contains:

  • The name of the initiating company.

  • The test Uniform Resource Locator (URL) and production URL information.

  • A reference to specifications and instance data.

After a SEED package is created, trading partners (recipients) can download the file, install it, and then configure it with additional information, such as their:

  • Port information (which includes the test drop location)

  • Receive drop location

Because each trading partner relationship is unique, it is necessary for the recipient to specify these unique attributes.

The following topics are covered in this section:

  • For comprehensive information about BizTalk SEED Wizard, see About BizTalk SEED Wizard.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk SEED Wizard Tasks.

  • For detailed procedures on how to accomplish tasks, see How To Perform BizTalk SEED Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk SEED Wizard.


About BizTalk SEED Wizard

The BizTalk SEED Wizard enables a company, referred to as the initiator in the wizard, to create a SEED package and make it available to trading partners, referred to as the recipients in the wizard. A recipient is able to open a SEED package, configure and test it, and begin sending documents to the deployment initiator's test site. If the recipient is successful in testing documents with the site, then the deployment initiator can integrate the SEED package configuration into the production environment and begin transactions with the recipient.

The following table lists the tasks included in a rapid deployment process.

Task | Who or what accomplishes the task
Creating a SEED package | Initiator
Selecting the SEED package to send | Initiator
Sending or storing the SEED package | Initiator
Configuring the recipient's BizTalk Server system | Recipient
Testing the configuration locally on the recipient's system | Recipient
Testing the remote connection | Recipient
Using the configuration to move into production (outbound) | Initiator
Using the configuration to move into production (inbound) | Recipient

After a recipient configures the SEED package, the SEED package automatically configures the appropriate ports on the system of the recipient, which will enable the recipient to begin testing transactions with the initiating company. Ports are created on a per-document basis, not on a package basis. The port is created only after the recipient completes the configure and create process for a specific document.

The following topics are covered in this section:

  • Initiating a SEED Package

  • Receiving a SEED Package

  • Example of Initiator and Recipient Relationship

  • Understanding the ASP Pages in SEED


Initiating a SEED Package

A SEED package is created by an initiator using BizTalk SEED Wizard and made available to recipients through a Web site or file share location. A common scenario consists of a single company interacting with several trading partners of the same kind. The central company is called the initiator and the trading partners are called recipients.

When an initiator wants to set up a new relationship with a recipient, or simply start handling new documents from an existing recipient, the initiator uses the BizTalk SEED Wizard to create a SEED package. The SEED package consists of the following:

  • Initiator Name: The name of the company initiating the connection. This bullet item is global to the SEED package; however, the following bullets are specific to each document.

  • Test URL: http://test.<initiator name>/invoice (This is the test site to which the recipient will send documents during the remote testing phase.)

  • Production URL: http://www.<initiator URL>/b2b/invoices

  • Specification: c:\specification\invoice.xml

  • Data: The Extensible Markup Language (XML) instance data for the specification.

Related Topic

Create a SEED package


Receiving a SEED Package

As a recipient, you may have received a SEED package from a company or downloaded it from the company's Web site. After saving the SEED package to your computer, you can then use the BizTalk SEED Wizard to complete the configuration and test the process of receiving and sending documents.

When the SEED package is installed on your computer, it creates the necessary ports, channels, document definitions, and receive functions. The title of each port, channel, document definition, and receive function starts with the name of the SEED package. This naming scheme ensures that unique names are given to the SEED package objects. This naming scheme also makes the objects distinct from other SEED package objects that might have been installed on the BizTalk Servers.

The BizTalk SEED Wizard displays the following information about the SEED package on the Package Installation Process - Package Selection page:

  • Package ID. This is the generated Global Unique Identification (GUID) number.

  • Organization. This is the name specified by the initiating company who created the SEED package.

  • Document count. Specifies the number of documents within the SEED package.

  • Recommended operations. Indicates the tasks that might be involved in configuring, creating, and testing the package. Possible status includes:
    • There is at least one document to be configured.

    • There is at least one document to be installed.

    • There is at least one document to be tested locally.

    • There is at least one document to be remote tested.

    • There is at least one document to be switched to production.

    • The entire package is installed and is in production.

In addition, the wizard displays all of the documents associated with a SEED package on the Package Installation Process - Document Deployment page. For each document, you must perform the following tasks to verify and deploy the configuration:

  • Configure. This process configures the port property information. The status is either Configure Complete or Configure Incomplete.

  • Create. This process creates the necessary objects (for example, receive functions, ports, and channels). The status is either Create Passed, meaning the objects were created, or Create Failed, meaning the objects were not created.

  • Test Locally. When the wizard performs a local test, it drops the instance data for the specification in the directory you specified as Receive location for inbound documents or submits it synchronously to the remote URL for outbound documents. For documents marked as inbound, BizTalk Server then picks up the file and places it in the Test Drop Location for verification of the local test. The instance is picked up by the BizTalk SEED Wizard and verified for both the format and content, and the status of the specification is updated within the SEED package. This ensures that the format of the document is correct. If the instance format is correct, the status of the specification within the SEED package is updated. For documents marked as outbound, SubmitSync is called. BizTalk Server then processes the document and drops to the Final Drop Location. The BizTalk SEED Wizard then picks up the document from the Final Drop Location and verifies the data. Possible status includes:
    • Local Test in Process. The instance is being tested.

    • Local Test Passed. The instance was verified.

    • Local Test Failed. The instance was not verified.
  • Test Remotely. When the wizard performs a remote test for inbound documents, it updates the transport address to the initiator's TestURL, which is part of the SEED package. The document is then submitted synchronously to BizTalk Server. The initiator's Web site then returns the document as part of the HTTP response. The BizTalk SEED Wizard verifies the response. For documents marked as outbound, the date is wrapped in Extensible Markup Language (XML) headers, which contain the receiver's production URL and channel used to process the document. Using the specified channel, this page calls the Submit method, which posts the document back to the production URL (localsubmit.asp) on the initiator's Web site. The document is then dropped to the Final Drop Location where it is picked up and verified by the BizTalk SEED Wizard. This process should be repeated with each of the remaining specifications. For more information about the .asp pages, see Understanding the ASP Pages in SEED.

  • Deploy. You can only deploy documents marked as inbound. The status is either Deploy Passed, meaning the configuration was deployed, or Deploy Failed, meaning the configuration was not deployed.

Related Topic

Install a SEED package


Example of Initiator and Recipient Relationship

To understand the components that make up a SEED package, you must first understand the relationship between an initiator and a recipient. (This example describes a scenario that uses two fictitious companies as the initiator and recipient.) A typical scenario has an initiator, in this example Northwind Traders, and one or several recipients, in this example Contoso, Ltd. The Northwind Traders procurement department (the initiator of the deployment scenario) receives invoices from several of its trading partners (the recipients) for various maintenance request orders.

The procurement department has a Web site where it receives invoices from suppliers (recipients). The documents sent to this location are Extensible Markup Language (XML) files that adhere to a BizTalk Editor specification called Invoice.xml. Documents are verified when they are received at this location and at the test location of the recipient.

Northwind Traders also has a test site set up to receive documents and validate them against the specification. If the document matches the specification, the data is sent to the recipient. The test site is used as the location for all recipients to test their transactions before they send the files back to the production site of the initiator. Recipients send transactions to the initiator test site until the transactions are processed without any errors. This procedure ensures that the transactions exchanged through the production site will be successful.

Northwind Traders creates the SEED package and places the package on its Web site for its recipient to download. The recipient, Contoso, Ltd, downloads the SEED package and then uses BizTalk SEED Wizard to complete the configuration, which requires adding port and sometimes receive function information.

After Contoso, Ltd configures the SEED package, the BizTalk SEED Wizard creates the appropriate channel and port to configure the site of the recipient to communicate with the initiator test site. Contoso, Ltd tests the sample instance by submitting it to the channel (and to the port bound to the channel), which then sends it to the test ASP page.

After the test has been successfully completed, Contoso, Ltd can go live.

Related Topics

Initiating a SEED Package

Receiving a SEED Package


Understanding the ASP Pages in SEED

Three Active Server Pages (ASP) are included with BizTalk SEED Wizard: slingback.asp, trigger.asp, and localsubmit.asp. These ASP pages are located in the \Program Files\Microsoft Biztalk Server\SEED folder. Before you create a SEED package, you must set up a Web site and place the Slingback.asp, Trigger.asp, and Localsubmit.asp files on that site. These pages are designed to take posts. For more information about implementing a secure site, go to the MSDN Online Library Web site (www.msdn.microsoft.com/library/default.asp) and search for the article "Implementing a Secure Site with ASP."

The following describes how the BizTalk SEED Wizard uses them:

  • Slingback.asp. This ASP is used for remote testing of inbound documents. When creating a SEED package, the initiator must use this page, or one with the same functionality, in the URL for remote test box. When the recipient clicks the Test Remotely button, the document is submitted to BizTalk Server synchronously through slingback.asp. The document is then copied back to the recipient and the BizTalk SEED Wizard verifies that the document received back matches the one sent.

  • Trigger.asp. This ASP is used for remote testing of outbound documents. When creating a SEED package, the initiator must type trigger.asp in the URL for remote test box for outbound documents. The document is sent to the trigger.asp page with the production URL from the recipient and the channel the recipient used to process the document, all of which is wrapped in the Extensible Markup Language (XML) file. On the trigger.asp page (initiator side), an open destination submit is called with the production URL of the recipient (generally localsubmit.asp) as the transport address.

  • Localsubmit.asp. This ASP is used for remote testing of outbound documents. The recipient uses localsubmit.asp as the production URL. When localsubmit.asp receives the document, the channel is retrieved from the XML file and the document is submitted to Biztalk Server with the specified channel.

Related Topic

Create a SEED package


Why Perform BizTalk SEED Wizard Tasks

This section provides a quick reference about why you perform BizTalk SEED Wizard tasks. The following table identifies primary tasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Create a SEED package
 To create an Extensible Markup Language (XML) package that contains your BizTalk Server 2002 configuration (for both outgoing and incoming documents) that you can make available to teams within your organization or with trading partners to begin the process of exchanging data.
  • Install a SEED package
 To install an XML package that contains the initiator's BizTalk Server 2002 configuration (for both outgoing and incoming documents) that you can use to test the transaction process prior to conducting business within a production environment.


How To Perform BizTalk SEED Tasks

This section provides task-specific information about how to create and install a SEED package.

The following procedures are covered in this section:

  • Create a SEED package

  • Install a SEED package


Create a SEED package

Before you create a SEED package, you must set up a Web site and place the Slingback.asp, Trigger.asp, and Localsubmit.asp files (which are located in \Program Files\Microsoft BizTalk Server\SEED folder) on that site. These pages are designed to take posts. For more information about implementing a secure site, go to the MSDN Online Library Web site (www.msdn.microsoft.com/library/default.asp) and search for the article "Implementing a Secure Site with ASP."

  1. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk SEED Wizard.

    The BizTalk SEED Wizard opens.

  2. On the Welcome to the BizTalk SEED Wizard page, select Create SEED package and click Next.

  3. On the Package Creation Process - Organization Information page, type your organization name in the box.

    —Or—

    If necessary, click Browse to use an existing SEED package. The Open dialog box appears. Locate the SEED package you want to use and click Open.

    Important

    • Once you modify an existing SEED package, the Browse button is disabled. This means that you cannot go back to Package Creation Process - Organization Information page and reload the SEED package. To reload the same SEED package after making changes, click Cancel to exit the wizard. Open the BizTalk SEED Wizard again and on the Package Creation Process - Organization Information page, browse to the same SEED package.
  4. Click Next.

  5. On the Package Creation Process - Document Specifications page, click Add.

    The Configure Document dialog box appears.

  6. Click Browse next to the Specification box to locate a specification.

    The Select a Document Specification from the WebDAV Repository dialog box appears.

  7. Browse to the specification location, select the file, and then click Open.

  8. Click Browse next to the Test instance box to locate a document instance.

    The Open dialog box appears.

  9. Browse to the document instance location, select the file, and then click Open.

  10. Select either Inbound to initiator or Outbound from initiator.

  11. In the URL for remote test box, type the path to the server containing the Slingback.asp page if you selected Inbound to initiator in step 10 or Trigger.asp page if you selected Outbound from initiator in step 10. Then, if you selected Outbound from initiator in step 10, click OK. If you selected Inbound to initiator in step 10, go to step 12.

    Note

    • If you clicked OK, the Package Creation Process - Document Specifications page appears. If needed, complete step 13. Otherwise, go to step 14.
  12. If you selected Inbound to initiator, then in the Production URL box, type the path to your production server and click OK.

    The Package Creation Process - Document Specifications page appears. If needed, complete step 13. Otherwise, go to step 14.

  13. If you need to edit a document configuration:
    1. Select a specification from the Documents list and click Edit.

      The Configure Documents dialog box appears.

    2. Modify the options as specified in steps 3 through 9.

    If you need to remove a specification from the Documents list:

    • Select the specification from the Documents list and click Remove.
  14. Click Next.

  15. On the Completing the BizTalk SEED Wizard page, if necessary click Browse to specify a new location for the SEED package, and click Finish to install the package to the location specified in the SEED package path box.

    The BizTalk SEED Wizard message box appears.

  16. Click OK.

Related Topic

Example of Initiator and Recipient Relationship

Initiating a SEED Package

Install a SEED package

Understanding the ASP Pages in SEED


Install a SEED package

If you have not already done so, install all files (except Localsubmit.asp) to the directory you want. Install the Localsubmit.asp file to a virtual directory that can be accessed while configuring outbound documents contained within a SEED package.

  1. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk SEED Wizard.

    The BizTalk SEED Wizard opens.

  2. On the Welcome to the BizTalk SEED Wizard page, select Install SEED package and click Next.

  3. On the Package Installation Process - Package Selection page, click Browse to locate the SEED package.

    The Open dialog box appears.

  4. Browse to the SEED package location, select the file, and then click Open.

  5. Click Next.

  6. On the Package Installation Process - Test Information page, type a number in the Time out box, type a number in the Interval box, and then click Next.

    Important

    • If your SEED package contains large documents, test results might result in Timeout or Failed status.

    • The value in the Time out box is added to the administration cache value specified BizTalk Server group settings.
  7. On the Package Installation Process - Document Deployment page, select a specification from the Documents box, and click Configure.

    Important

    • If the document was originally configured as Inbound to initiator during the creation process, then the Inbound Document (to Initiator) Configuration dialog box appears. Proceed to step 9.

    • If the document was originally configured as Outbound to initiator during the creation process, then the Outbound Document (to Initiator) Configuration dialog box appears. Proceed to step 14.
  8. In the Inbound Document (to Initiator) Configuration dialog box, click Browse next to the Location box to specify a polling location for the receive function.

    The Browse for Folder dialog box appears.

    Note

    • The location you specify must be a different location than the one you specify in the Test drop location box.
  9. Select a receive function location and click OK.

  10. In the File types to poll for box, type the file types to locate.

    Note

    • If you are going to change the file type, be sure the default file type in the SEED package is included.
  11. Click Browse next to the Test drop location box to specify a test drop location.

    The Browse for Folder dialog box appears.

    Note

    • The location you specify must be a different location than the one you specify in the Location box in the Receive function area.
  12. Select a test drop location and click OK.

    The Package Installation Process - Document Deployment page appears.

  13. If your document was originally configured using the Inbound Document (to Initiator) Configuration option, then proceed to step 16.

  14. In the Outbound Document (to Initiator) Configuration dialog box, in the Production URL box, type location of the localsubmit.asp page.

  15. In the Final Drop Location box, click Browse to specify the final drop location for testing outbound documents and click OK.

  16. Click Create.

    Note

    • The Create button will change to a Remove button when the creation process is completed.
  17. Click Test Locally to verify local configuration only.

  18. Click Test Remotely to verify remote connectivity to initiator.

    If the Initiator field for the document is marked Outbound, go to step 20.

  19. Click Deploy.

    The Deploy button is enabled only if the Initiator field for the document is marked Inbound.

  20. Click Next.

    The Completing the BizTalk SEED Wizard page appears.

  21. Click Finish.

  22. Click OK to close the BizTalk SEED Wizard Message box.

Related Topic

Example of Initiator and Recipient Relationship

Receiving a SEED Package


Troubleshooting BizTalk SEED Wizard

This section provides troubleshooting information about SEED packages.

The following topic is covered in this section:

  • Test Locally or Test Remotely fails or times out


Test Locally or Test Remotely fails or times out

Cause: The Test Locally or Test Remotely options for outbound documents indicate a time out.

Solutions:

  1. Check the Event Log. If there is no error logged for the file, increase the amount of time specified in the Time out box on the Package Installation Process - Test Information page.

  2. If errors exist in the Event Log for the file, then resolve the errors per the Event Log information.

  3. If the document instance contained in the SEED package has the same name as another file in the test drop location, BizTalk Server will append the document instance contained in the SEED package to the file that exists in the test drop location. This will cause the document instance to no longer match the sample instance that is contained in the SEED package. Rename the file that exists in the test location or remove that file and then click Test Locally or Test Remotely.

Cause: The Test Remotely option for inbound documents fails.

Solutions:

  1. Check the Event Log. If there is no error logged for the file, increase the amount of time specified in the Time out box on the Package Installation Process - Test Information page.

  2. If errors exist in the Event Log for the file, then resolve the errors per the Event Log information.

  3. If the document instance contained in the SEED package has the same name as another file in the test drop location, BizTalk Server will append the document instance contained in the SEED package to the file that exists in the test drop location. This will cause the document instance to no longer match the sample instance that is contained in the SEED package. Rename the file that exists in the test location or remove the file and then click Test Locally or Test Remotely.

  4. If the issue is because the initiator system is unresponsive, wait a short time and then click Test Remotely.


Deploying BizTalk Server Resource Applications

Microsoft® Application Center 2000 can be used to deploy a Microsoft BizTalk™ Server 2002 configuration from one configuration to another, such as moving a configuration from a test environment to a production environment. Using Application Center to deploy environments greatly reduces both the time it takes to move configurations and the amount of manual configuration associated with such a move.

The BizTalk Server replication driver extends Application Center to allow replication of BizTalk resources to all members of a cluster and between clusters. The driver uses the existing replication support of Application Center.

This driver replaces the previous deployment method (BTConfigAssistant) featured in BizTalk Server 2000. BTConfigAssistant, a Microsoft Visual Basic® sample application that was included with the first release of BizTalk Server, extracted configuration information and enabled companies to deploy applications. This method is still available in BizTalk Server 2002; however, the preferred method for deploying applications is to use Application Center.

The following topics are covered in this section:

  • For comprehensive information about deployment, see About BizTalk Server Deployment.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Server Deployment Tasks.

  • For detailed procedures on how to accomplish tasks, see How To Perform BizTalk Server Deployment Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk Server Deployment.


About BizTalk Server Deployment

Microsoft Application Center 2000, one of the .NET Enterprise Servers, supports deployment of several BizTalk Server resources, such as ports (including all objects that are bound to ports, such as channels) and port groups, along with files, COM+ applications, registry keys, Web sites and virtual directories, and data sources.

A typical BizTalk Server production environment consists of a BizTalk Messaging Management database that stores the necessary messaging configuration information, and a group of applications servers that share the messaging configuration. Each server within the cluster contains the required XLANG schedules, COM+ applications associated with the XLANG schedules, and information regarding which BizTalk Messaging Management database to use when deploying an application.

When you are deploying an application, the BizTalk Messaging Management database must be available to both the source and target computers because only a central WebDAV repository is supported.

Important

  • You must add a local system account (system\<computer name>) to a remote Microsoft® SQL Server™ to prevent the Application Center driver from failing when SQL Server is remote. To access the BizTalk Messaging Management database (InterchangeBTM) from an Application Center cluster, it must be local to the Application Center cluster controller, or it must be outside of the Application Center cluster. The BizTalk Server replication driver might not be able to access the BizTalk Messaging Management database if it is hosted on a member of the Application Center cluster.

The BizTalk Server replication driver on Application Center has two primary functions:

  1. Move local resources. This task requires the source server to reference its local resources and replicate them to a target server. Automatic replication is supported.

  2. Move shared resources. This task requires collecting the appropriate information from the BizTalk Messaging Management database, and then persisting that information and transmitting it to the target server. Automatic replication is not supported.

To move shared resources, Application Center (using the BizTalk Server replication driver) on the source server contacts the BizTalk Messaging Management database using the BizTalk Messaging Configuration object model, rather than reading directly from the SQL Server database. This process protects against future changes in the BizTalk Server configuration and ensures object model constraints are enforced.

Given the following three system configuration scenarios, the process of transferring shared information would be as follows:

Two clusters that share the same configuration database.

In the previous illustration, two clusters are shown. Each member in a cluster refers to the same BizTalk Messaging Management database. Therefore, when data is synchronized between cluster members in either cluster, configuration information does not need to be transferred. However, when an application is deployed, configuration information will need to be transferred because each cluster uses its own BizTalk Messaging Management database.

Clusters that share one BizTalk Messaging Management database

The previous illustration shows how an application would be deployed within a cluster where the BizTalk Messaging Management database is shared. In this scenario, even "out-of-cluster" deployments would not require any shared resource to be transferred.

Clusters that use different BizTalk Messaging Management databases

In the previous illustration, individual members within a cluster use different BizTalk Messaging Management databases. Because there are multiple databases for each cluster member, potentially all synchronizations would require the transfer of both local and shared information in the respective BizTalk Messaging Management databases.

Important

  • The last scenario is not supported in the current versions of Application Center and BizTalk Server. However, this system configuration should function properly, enabling you to deploy applications.

Regardless of the system configuration scenario you are working with, the following pattern applies when shared information needs to be transferred between databases:

  1. The BizTalk Server replication driver on the source server sends a request containing the names of the shared resources present on the source server to the target database to determine what data needs to be updated.

  2. The driver on the target server returns an Action list containing the additions, updates, and deletions necessary to synchronize the shared resources.

  3. The source server reads the appropriate information from its database using the BizTalk Messaging Configuration object model and generates a manifest of what needs to be transferred.

  4. The BizTalk Server replication driver on the source server delegates the manifest to the Application Center File System replication driver for transfer to the target server.

  5. The driver on the source server sends an update list containing the changes to apply to the target server. This list includes references to the manifest propagated to the target server.

  6. On the target server, the BizTalk Server replication driver reads the manifest and makes the appropriate changes in its corresponding BizTalk Messaging Management database.

The basic process for deploying a new or existing application includes the following:

  1. If necessary, you must create a cluster on the computer you are deploying from and the one you will be deploying to. In addition, you will need to define an Application Center cluster corresponding to a BizTalk Server group, and define one computer as the controller of that cluster.

  2. Create a new application or select an existing application in Application Center.

  3. Add BizTalk resources and other resources such as files, COM+ applications, and registry keys, as needed.

  4. Deploy the application from the source computer to the target computer.

The following topics are covered in this section:

  • About Clusters

  • Creating New Applications

  • Adding Resources

  • Deploying Applications


About Clusters

Microsoft Application Center enables you to manage multiple clusters from a single computer. Using Application Center, you can:

  • Create clusters

  • Join existing clusters

  • Add and remove cluster members

  • Deploy new content

  • Configure load balancing

  • Monitor cluster performance

In addition, it provides a single, unified image of the content that is installed across a cluster. To help you with this content, Application Center provides wizards, such as the New Cluster Wizard, to simplify the process of creating and managing clusters and deploying content.

An Application Center cluster can serve corporate intranet clients or external Internet clients. The client software can be "thin-client" (such as Web browsers) or "thick-client" applications (such as Microsoft Visual Basic programs). Application Center clusters are designed to manage both the Web tier, which serves HTTP clients, and the business logic tier, which serves Distributed Component Object Model (DCOM) traffic.

Important

  • Microsoft Application Center uses Microsoft® Windows® Authentication to access the BizTalk Messaging Management database (InterchangeBTM) from an Application Center cluster. To access the BizTalk Messaging Management database (InterchangeBTM) from an Application Center cluster, the BizTalk Messaging Management database must be local to the Application Center cluster controller, or the BizTalk Messaging Management database must be outside of the Application Center cluster. If the BizTalk Messaging Management database is outside the Application Center cluster, you must add a local system account to a remote SQL Server to prevent the Application Center driver from failing when SQL Server is remote. You may not be able to access the BizTalk Messaging Management database if SQL Server, which the database is local to, is a member of the Application Center cluster but not the cluster controller. For detailed instructions on how to add a SQL Server login account, see the "Remote SQL Server login account" topic in SQL Server and BizTalk Server 2002 Database Interactions.

Note

  • You can use Application Center to manage availability and application deployment on stand-alone (non-clustered) servers or servers that are not running Web sites. In these cases, Application Center treats the stand-alone server as a "cluster of one."


Creating New Applications

In the context of Microsoft Application Center, an application is a manifest listing resources that are synchronized within, or deployed to, a cluster. An application contains resources by listing references to them, thus more than one application can list the same resource. When you synchronize or deploy an Application Center application, the resources listed in the application are also synchronized or deployed.

By creating new Application Center applications, you can manage synchronization and deployment for your resources, including BizTalk resources. For more information about creating new Application Center applications, see Application Server 2000 Help. Using applications in this way gives you more control over what resources are synchronized or deployed and when. In addition, you can create an application that lists a subset of a default application or lists resources that are not listed in a default application.


Adding Resources

Microsoft Application Center enables you to add resources to an application. A BizTalk resource can be thought of as an object with a unique name and a set of properties. Biztalk resources, such as ports, port groups, custom counters, and receive functions, represent the configuration for a particular application that relies on Microsoft BizTalk Server. You specify the resources you want to associate with an application that you want to deploy.

Important

  • The plus sign (+) should not be used in resource names because it is converted in .asp (on the server) to a space. For example, "BizTalkorg+port" would be converted to "BizTalkorg port". If you deploy an application that contains a resource name with a plus sign, a manifest will not be generated and files will not be transferred. However, Application Center will indicate that the application has been successfully deployed. If you have a resource that contains a plus sign in its name, replace the symbol with %2B on your client computer.

The following table describes the type of BizTalk resources you can add to an application and the specific items that are automatically included.

BizTalk resource Items automatically added Notes
Port All associated:
  • Channels

  • Document definitions

  • Organizations

  • Envelopes
  • All elements linked to the port are deployed; however, unbound items such as documents and envelopes are not moved automatically. Examples include envelopes and documents that are envelopes, which are used to parse incoming flat files, and documents that are used to parse incoming receipts.
Port Group

(Distribution Group)

 All ports in the group.

All items added for a port, for each port in the port group.
  • All elements linked to the port group are deployed; however, unbound items such as documents and envelopes are not moved automatically. Examples include envelopes and documents that are envelopes, which are used to parse incoming flat files, and documents that are used to parse incoming receipts.
Receive Function No additional items are added.
  • If necessary, you must manually add the file system resource used by the receive function or create Message Queuing (also known as MSMQ) on the target server.
Custom Counter No additional items are added.
  • There are various properties and restrictions to consider with custom counters. For more information, see Custom Counters, Creating a Custom Counter Using WMI, and Custom Counter Query Properties.

In addition to BizTalk resources, Application Center enables you to add the following resources:

  • File System Path

  • Registry Keys

  • Web Sites and Virtual Directories

  • COM+ Applications

  • Data Sources

File System Path

Displays replication of file system folders. For example, you can use the File System Path resource to deploy XLANG schedules or directories used by receive functions and file transport.

Important

  • You must use the File System Path resource to add XLANG schedules (.skx files) to the application you want to deploy. XLANG schedules must be locally stored on the computer that they will be running on.

Registry Keys

Provides access to the registry. Synchronizing an entire registry across a cluster can cause significant conflicts on Cluster Members, and therefore is not recommended.

Web Sites and Virtual Directories

Provides a list of Internet Information Services (IIS) Web sites and virtual directories available (including files, certificates, certificate trust lists, and ISAPI filters referenced by the site or virtual directory). When specifying these, you need to add only the Web site or virtual directory. You do not need to specify the physical directories or files that make up the Web site or virtual directory explicitly. For example, HTTP receive functions and Web sites that trading partners reply to.

Note

  • Application Center synchronizes resources that are specified only on the local file system and does not synchronize resources that are specified with a UNC path or on removable media.

COM+ Applications

Displays all available COM+ applications, proxies, and components. You can use this to move application integration components (AICs) and components in schedules, provided they are COM+ applications. For more information, see Application Center 2000 Help.

Important

  • You must use the COM+ Applications resource to add any COM+ applications that have been bound to XLANG schedules for applications being deployed.

  • Only COM+ applications that are properly registered, on the computer they are running on, with Component Services on the local server can be added. If a COM+ application does not appear in the Application Center snap-in, you cannot add it to an application. To add COM components to application lists, you must install them into COM+ Applications.

Data Sources

Specifies the system data source names (DSNs) available. Only DSNs on the local server are available to add to applications. DSNs on remote servers are not available until you create them on the local server.


Deploying Applications

Deployment is the process of copying an initial Microsoft Application Center application image from one cluster to another. Typically, deployment occurs from a staging cluster to a production cluster that holds the live content. During deployment, the application image is copied to the cluster controller of the recipient cluster.

The following topics are covered in this section:

  • Planning a Deployment

  • Pre-Deployment Checklist

  • Post-Deployment Checklist

  • Items That Are Not Deployed and/or Replicated

  • Synchronization of BizTalk Resources


Planning a Deployment

Before you deploy applications, identify the resources that constitute the BizTalk application. Resources are either of the following:

  • Configuration Information (stored in the BizTalk Messaging Management database), which include:
    • Ports (automatically includes associated channels, document definitions, envelopes, and organizations)

    • Distribution lists

    • Receive functions

    • Custom counters
  • External Components, which include:
    • Files

    • Registry keys

    • Application integration components (AICs)

    • Certificates

    • Message queues (MSMQs)

    • XLANG schedules (.skx files)

    • Custom components (encryption, encoding, serialization)

Once the resources are identified, group the resources into Application Center applications.


Pre-Deployment Checklist

Before you deploy an application with BizTalk resources, ensure that you have addressed the following issues.

Source cluster

  • Make sure the BizTalk Messaging Management database is accessible.

  • Ensure the WebDAV repository is accessible.

  • There is no automatic mapping of variables such as transport addresses because these types of variables vary from one environment to another. Transport addresses must be manually changed.

  • XLANG schedules (.skx files) must be copied directly to the cluster where the application is being deployed.

  • Starting and stopping services after or before deploying an application must be completed if you need to immediately refresh the cache. For more information, see Start a server in a group or Stop a server in a group. For information about adjusting the refresh interval of a server, see Configure general properties for a server group.

  • Prior to updating an already deployed application that contains BizTalk resources, ensure that all long-running transactions have completed.

Target cluster

  • Make sure the BizTalk Messaging Management database is accessible.

  • Ensure the Simple Mail Transfer Protocol (SMTP) host is set for each BizTalk Server group and reliable messaging reply-to URL. Use the BizTalk Server Administration console.

  • Ensure the required certificates are present, because certificates are not automatically deployed.

  • Ensure the WebDAV repository is accessible, otherwise document definitions and envelopes might not replicate.

  • Register the application integration components (AICs) on the target server.

  • Create the message queues required by the Message Queuing receive functions.

  • Stop processing servers.


Post-Deployment Checklist

Once you have deployed an application, meaning it has successfully been added to the target computer, you must manually make some modifications to complete the deployment process for the application that now exists on the target computer. This topic outlines areas you might need to address, depending on the resources associated with the application you deployed.

Databases

When deployment is complete, you need to make some minor adjustments on the target computer. For example, if your application uses correlation databases you must manually copy the correlation databases to the SQL Server instance of the target computer. For step-by-step instructions on how to do this, seethe "Attach the databases" functionality described in the Preliminary Setup section for the E-Procurement Sample. You can also use the Data Transformation Services (DTS) of SQL Server to export the databases to the SQL Server instance of the target computer.

Receive functions

You might need to enable all the BizTalk receive functions used by an application. You can enable the receive functions in BizTalk Server Administration or programmatically through the BizTalk Server Windows Management Instrumentation (WMI) provider. You might need to do this because the receive functions are created before message queues, which are created manually. BizTalk Server automatically disables receive functions if their corresponding polling locations (such as a directory) are not accessible.

The processing server of the receive functions might need to be updated. Each receive function is associated with a processing server. The names of processing servers in the source cluster are mapped to the name of the target server, typically the cluster controller, in the target cluster. You can update the processing server of the receive functions by using BizTalk Server Administration or programmatically through the WMI provider.

If you replicate receive functions that are configured to use a user name and password, the receive function will be disabled due to a non-existent password. To resolve this issue, you need to bring up the property page for each receive function, re-enter the password, and then enable the receive function.

Ports

If you deployed an Application Center application with BizTalk ports, then the ports on the target computer need to be updated so that the primary and secondary port addresses reference the correct locations. For example, http://TestAURL might need to be changed to http://ProductionAURL. When Application Center deploys the BizTalk Server configuration from one computer to another, it does not modify the BizTalk ports.

Note

  • You might need to start and stop the BizTalk service for these changes to take effect. You can start and stop the BizTalk service in the BizTalk Server Administration tool. For more information, see Start a BizTalk service and Stop a BizTalk service.

Processing servers

You must start processing servers after you have deployed an application.


Items That Are Not Deployed and/or Replicated

Documents and envelopes that are not bound to ports are not deployed. Examples include envelopes and documents that are envelopes, which are used to parse incoming flat files, and documents that are used to parse incoming receipts. Certificates used by ports and channels for encryption, decryption, and signing are not replicated. They must be copied directly to the cluster where the application is being deployed. The same is true for other objects that are not replicated, such as certificates.

Objects that are not replicated should exist on the target server prior to deploying an application. For example, if you have an Application Center application that has a channel that uses an application integration component (AIC) and you deploy the application, there is no guarantee that the COM+ application, which contains the AIC, will be created before the channel that references the AIC is created.

File hierarchies for receive functions and Message Queuing queues also are not replicated. This is because receive functions and Message Queuing queues are associated with particular BizTalk Server processing servers, which are identified by name. For example, receive functions R1 and R2 associated with Test1 and Test2 computers in a test environment would need to be associated with ProdA and ProdB computers in a production environment. Message Queuing bound to schedules must be copied directly to the cluster where the application is being deployed.


Synchronization of BizTalk Resources

Unlike the rest of the Application Center resources, BizTalk resources are not automatically synchronized. Therefore, if you make changes to any BizTalk resource for an Application Center application that has already been deployed, you will need to re-deploy the Application Center application. For more information about how to deploy an Application Center application that contains BizTalk resources, see Deploy an Application Center application to a target server.


Why Perform BizTalk Server Deployment Tasks

This section provides a quick reference about why you perform BizTalk Server Deployment tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Create an Application Center application that contains BizTalk resources
 To logically group BizTalk configuration information like ports, application integration components (AICs), XLANG schedules, and other resources that make a BizTalk application a deployable unit.
  • Deploy an Application Center application to a target server
 To move newly developed BizTalk applications from a development environment to testing or production environments.
  • Delete BizTalk resources from a target server
 To remove unused or obsolete resources.


How To Perform BizTalk Server Deployment Tasks

This section provides task-specific information about how to create a new Application Center application or modify an existing Application Center application that contains BizTalk resources, and how to deploy the Application Center application to a target computer.

The following topics are covered in this section:

  • Create an Application Center application that contains BizTalk resources

  • Deploy an Application Center application to a target server

  • Delete BizTalk resources from a target server


Create an Application Center application that contains BizTalk resources

It is recommended that you deploy resources individually, rather than adding a folder containing resources. If you deploy resources by selecting a folder, and later need to remove one of the resources, you will need to completely remove all the resources from the deployment computer. For more information about deleting resources, see Delete BizTalk resources from a target server.

  1. Click Start, point to Programs, point to Administrative Tools, and then click Application Center.

    Microsoft Application Center 2000 opens.

  2. Expand Application Center, expand the cluster that you want to add your Application Center application to, and then click Applications.

  3. In the Applications pane, click New or, on the Applications pane, you can select an existing Application Center application from the Name column.

    The Create a new application – Web Page Dialog dialog box appears.

  4. In the Name box, type a name for your Application Center application and click OK.

    The name of your Application Center application appears in the Name column of the Applications pane.

  5. Select the Application Center application you just created and, in the Contents pane, select BizTalk from the Resource Type list to add BizTalk resources, and then click Add.

    The Add Resource – Web Page Dialog dialog box appears.

  6. To add all resources for a BizTalk resource type, select the resource type and click Add or, to select individual resources, double-click the resource (BizTalkCustomCounters, BizTalkPortGroups, BizTalkPorts, or BizTalkReceiveFunctions) you want to add.

    The Add Resource – Web Page Dialog dialog box appears.

    Note

    • In BizTalk Messaging Manager, distribution lists are the same as BizTalkPortGroups resource types.
  7. Select the resource you want to add and click Add.

  8. Repeat steps 6 and 7 until you have added all the resources you want. If you are adding individual resources, click Close when you have added all necessary resources.

  9. To add XLANG schedules, in the Contents pane, select File System Paths from the Resource Type list.

    The Add Resource – Web Page Dialog dialog box appears.

  10. Browse to the schedule file location, select it, and click Add. Repeat this process until you have the necessary schedule files, and then click Close.


Deploy an Application Center application to a target server

  1. Click Start, point to Programs, point to Administrative Tools, and then click Application Center.

    Microsoft Application Center 2000 opens.

  2. Expand Application Center, right-click the cluster that contains the Application Center application you want to deploy, and then click New Deployment.

    The New Deployment Wizard opens.

  3. Click Next.

  4. On the Deployment Target Options page, type a name in the Deployment name box, or leave the default name.

  5. Select Deploy content outside the current cluster and click Next.

  6. On the Deployment Target Authentication page, type the appropriate credentials in the User name, Password, and Domain boxes, and click Next.

  7. On the Deployment Target page, in the Target box, type the name of the computer you want to deploy the Application Center application to, or click Browse to browse to the location.

    Note

    • You need to deploy BizTalk resources only to the Application Center controller.
  8. Click Add.

  9. On the Deployment Content page, select either Deploy all applications and related cluster configurations or Deploy one or more applications.

    If you select the Deploy one or more applications option, select the Application Center application(s) you want to deploy from the list. To select multiple items, press and hold CTRL, and then click each item.

  10. Click Next.

  11. On the Deployment Options page, select the appropriate check box. If necessary, clear the Deploy folder and file permissions (NTFS only) check box.

  12. Click Next.

  13. On the Completing the New Deployment Wizard page, click Finish.

Important

  • If you replicate receive functions that are configured to use a user name and password, the receive function will be disabled due to a non-existent password. Passwords must be re-entered because, to ensure security, the BizTalk Server replication driver does not replicate passwords. To resolve this issue, you need to bring up the property page for each receive function, re-enter the password, and then enable the receive function.


Delete BizTalk resources from a target server

If you have already deployed an Application Center application to a target server and want to delete resources associated with that Application Center application, you must do the following:

  1. Add the individual resource you want to delete from the computer you are deploying to and then deploy the application. For more information, see Deploy an Application Center application to a target server.

  2. Delete the BizTalk resources from the computer you used to deploy the Application Center application. The following table lists what to use to delete particular resources.
    To remove | Use | Additional information
    BizTalkPortGroups resources (also called distribution lists) | BizTalk Messaging Manager or the BizTalk Messaging Configuration object model (accessible using Microsoft Visual Basic Scripting Edition (VBScript) | For more information, see Delete distribution lists.
    BizTalkPorts resources | BizTalk Messaging Manager or the BizTalk Messaging Configuration object model (accessible using VBScript | For more information, Delete messaging ports.
    BizTalkReceiveFunctions resources | BizTalk Server Administration or the BizTalk Server Windows Management Instrumentation (WMI) provider (accessible using VBScript | For more information, see Delete a receive function.
    Schedule file resources | Windows Explorer | For more information, see Windows 2000 Help.
    BizTalkCustomCounters resources | BizTalk Server Administration or the BizTalk Server WMI provider | None.

  3. Re-deploy the Application Center application with the resource that you want to remove from the computer you are deploying to. For more information, see Deploy an Application Center application to a target server.


Troubleshooting BizTalk Server Deployment

This section provides a centralized location for information related to troubleshooting the deployment of Microsoft Application Center 2000 applications that contain BizTalk resources. If you are having difficulty deploying an Application Center application, try to find a solution in this section.

The following topics are covered in this section:

  • Deployed Application Center application requires updated resources

  • Error message indicates that administrative privilege credentials are required


Deployed Application Center application requires updated resources

Cause: The Web Distributed Authoring and Versioning (WebDAV) repository reference URL or file name has been changed for a BizTalk document (see the New Document Definitions tab in BizTalk Messaging Manager) that has been deployed as part of an Application Center application.

Solution: Delete the resources from the target computer and re-deploy the Application Center application. To do this:

  1. Delete the resources from the computer you used to deploy the Application Center application. The following table lists what to use to delete particular resources.
    To remove | Use | Additional information
    BizTalkPortGroups resources (also called distribution lists) | BizTalk Messaging Manager or the BizTalk Messaging Configuration object model (accessible using Microsoft Visual Basic Scripting Edition (VBScript) | For more information, see Delete distribution lists.
    BizTalkPorts resources | BizTalk Messaging Manager or the BizTalk Messaging Configuration object model (accessible using VBScript | For more information, Delete messaging ports.
    BizTalkReceiveFunctions resources | BizTalk Server Administration or the BizTalk Server Windows Management Instrumentation (WMI) provider (accessible using VBScript | For more information, see Delete a receive function.
    Schedule file resources | Windows Explorer | For more information, see Windows 2000 Help.
    BizTalkCustomCounters resources | BizTalk Server Administration or the BizTalk Server WMI provider | None.

  2. Re-deploy the Application Center application. For more information, see Deploy an application to a target server.

  3. Modify the WebDAV repository reference URL or file name for the document.

  4. Create a port and channel for the document. For more information, see Create messaging ports and Create channels.

  5. Re-deploy the Application Center application containing the modified document. For more information, see Deploy an Application Center application to a target server.


Error message indicates that administrative privilege credentials are required

Cause: When you try to deploy your Application Center application that contains BizTalk resources to another computer (target server), you get an error messaging indicating that administrative privilege credentials are required. The error message appears in the event log of the controller in the target cluster.

Solution: Configure administrative privileges for BizTalk Server for the target server and deploy the Application Center application again.

Note

  • The user does not need privileges as an administrator for the BizTalk Server Administrators group; however, the user needs privileges as an administrator for the target server.


Designing BizTalk Orchestrations

Microsoft® BizTalk™ Orchestration Designer is a Microsoft Visio® 2000–based design tool that enables you to create business process drawings that can be compiled and run as XLANG schedules. XLANG is an XML-based language. An XLANG schedule describes the business process and the binding of that process to application services.

You can use BizTalk Orchestration Designer to create drawings that describe long-running, loosely coupled, executable business processes. Typically, these drawings describe the way interactions and procedures are performed during the completion of a specified process, such as a purchase order request. Often, these business processes are not constrained by time limits. Also, the steps within a business process are loosely coupled. The description of the business process is separate from the implementation logic and sequencing used to perform the process.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Orchestration Designer, see About BizTalk Orchestration Designer.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Orchestration Designer Tasks.

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Orchestration Designer Tasks.


About BizTalk Orchestration Designer

This section provides detailed conceptual information that is essential to understanding BizTalk Orchestration Designer. It provides detailed information about the following topics:

  • BizTalk Orchestration Services

  • Creating XLANG Schedule Drawings

  • Compiling XLANG Schedules

  • Debugging XLANG Schedules

  • Running XLANG Schedules

  • Pooling XLANG Schedules

  • Managing Session State

  • Updating XLANG Schedules

Note

  • It is highly recommended that you review the How to Perform BizTalk Orchestration Designer Tasks section for task-specific information about using BizTalk Orchestration Designer.


BizTalk Orchestration Services

BizTalk Orchestration Services extends the capabilities of established information-exchange technologies. It enables users to create detailed representations of business processes that can be implemented programmatically within an integrated design environment.

Business-process design and implementation have traditionally been performed in two distinct phases: the visual-design phase and the coding phase. The visual-design phase typically consisted of the analysis of an existing business process (such as corporate procurement) and the creation of a workflow diagram or an interaction diagram to describe the process. The coding phase was usually performed separately. In this paradigm, you would build an abstract visual model of a business process and then map the model to an implementation framework.

One of the important features of BizTalk Orchestration is the integration of these previously distinct phases within a unified design environment. This design environment provides a versatile drawing surface and a comprehensive set of implementation tools. BizTalk Orchestration enables you to:

  • Create XLANG schedule drawings that describe business processes.

  • Implement business processes by connecting specific actions within a drawing to ports that represent locations to which messages are sent, or from which messages are received. Ports are named locations, and messages represent the data sent or received between actions and ports.

  • Define the flow of data between messages within business processes.

  • Compile XLANG schedule drawings into XLANG schedules. XLANG schedules are executable Extensible Markup Language (XML) representations of the information contained within the drawings.

In addition to the integration of design and implementation functionality, BizTalk Orchestration provides an important additional feature: the ability to create robust, long-running, loosely coupled business processes that span organizations, platforms, and applications. During an asynchronous, loosely coupled, long-running business process, a product that is ordered over the Internet might have to be built from parts that are in inventory. Some of these parts might even be temporarily out of stock. The entire business process might take weeks or months to complete. In contrast, a tightly coupled business process involves the synchronous exchange of messages. For example, when a customer withdraws money from a bank account, the debiting of the account is immediately followed by the delivery of the money.

BizTalk Orchestration enables you to:

  • Create a visual representation of long-running business processes.

  • Facilitate the exchange of messages by connecting the actions in your visual representation to ports that are implemented by a certain technology.

  • Compile the completed drawing into an executable XML representation of the drawing.

  • Reliably execute business processes that might take weeks or months to complete.

The following topics are covered in this section:

  • Understanding Business Processes

  • BizTalk Orchestration Designer Environment

  • XLANG Schedules

Related Topics

Creating XLANG Schedule Drawings

Understanding Business Processes


Understanding Business Processes

Business processes are as important to business management as assembly lines are to manufacturing. Adhering to a well-defined, formalized set of processes can enable any business to increase productivity and lower costs. A business process defines the message exchange protocol between all the distributed participants. To define a business process, you must determine the logical order of actions and the corresponding flow of messages. A business process does not include definitions of the distributed participants who perform these actions.

The sequence of steps in a long-running business process is typically asynchronous. Each step is an action that can be performed by one or more independent, distributed participants. These actions can result in the sending and receiving of messages among the participants, who might or might not be people performing related tasks. A distributed participant might be an automated process that responds to input, or the participant might even be an entirely separate business process. To understand business processes, you must be able to visualize a complex variety of relationships and dependencies. Business process modeling tools, such as workflow diagrams and interaction diagrams, have been developed to visually describe these relationships.

The following topics are covered in this section:

  • Workflow Diagrams

  • Interaction Diagrams


Workflow Diagrams

Workflow is a business-process design technology that automates and improves procedures within organizations. It is a useful technology for delineating the steps that must be taken, the dependencies that must be enforced, and the approvals that must be obtained during the completion of projects. You can use a workflow application to assign tasks to participants, define individual responsibilities, and describe the relationships among the participants. You can also use a workflow application to set time limits for the completion of projects and the achievement of milestones. However, the workflow technology is typically highly centralized. Participants are assigned tasks and given deadlines, but the workflow engine is responsible for routing completed work items from one participant to the next, and enforcing a schedule. In contrast, BizTalk Orchestration is broader in scope. Participants are autonomous and the responsibility for routing a work item from one participant to another is determined by the participants, not by a centralized application.

Related Topics

Interaction Diagrams

Understanding Business Processes


Interaction Diagrams

An interaction diagram describes the data flow within a business process and the messages that are exchanged. BizTalk Orchestration extends the interaction diagram concept by providing definition and control for decisions, concurrent actions, transactions, and supporting actions that cannot be included in an interaction diagram. Designing a business process by using BizTalk Orchestration results in a compiled, executable business process (an XLANG schedule). In contrast, interaction diagrams are static representations of business processes.

The following illustration shows a typical interaction diagram for an automated procurement system.

An interaction diagram

Related Topics

Understanding Business Processes

Workflow Diagrams


BizTalk Orchestration Designer Environment

BizTalk Orchestration Designer enables you to create XLANG schedule drawings. An XLANG schedule drawing is a representation of a business process. The drawing is saved as an .skv file, which is a customized version of the Microsoft Visio 2000 file format. The XLANG schedule drawing can then be compiled into an XLANG schedule, which is an XML-structured .skx text file that the XLANG Scheduler Engine understands. BizTalk Orchestration Designer enables you to create XLANG schedule drawings that include:

  • A visual description of a business process. This aspect of an XLANG schedule drawing is similar to a workflow diagram or an interaction diagram.

  • A visual representation of configurable ports. This is the implementation aspect of an XLANG schedule drawing.

  • A visual representation of the connections between shapes. Flowchart shapes can be connected to represent process flow in a business process, and actions can be connected to ports to represent the flow of communication in a business process.

  • A visual representation of the flow between specified message fields. This aspect of an XLANG schedule drawing determines the relationship between a message field on one message and another message field on a different message. By correlating these relationships, you can enable data-sensitive routing.

An XLANG schedule drawing is a representation of the procedures that are performed during a business process. An XLANG schedule drawing can define:

  • The message-exchange protocol that trading partners agree to use.

  • Actions that are used to send or receive messages that describe the logical sequence in which actions occur.

  • The implementation of ports and the actions to which they are linked.

  • The data flow between message fields.

The following topics are covered in this section:

  • Design Pages

  • Flowchart Shapes

  • Implementation Shapes

  • Communication Shapes

  • BizTalk Orchestration Designer Shortcut Keys


Design Pages

There are four design pages that are accessible within BizTalk Orchestration Designer. You can use these design pages to create different aspects of your XLANG schedule drawing.

  • Business Process page. On this page you can use Flowchart shapes and Implementation shapes to define a business process. For more information about using these shapes, see Flowchart Shapes and Implementation Shapes.

  • Data page. On this page you can use Communication shapes to control the flow of data between message fields. BizTalk Orchestration Designer provides these shapes automatically. For more information about using these shapes, see Communication Shapes.

  • On Failure of Transaction page. On this page you can use Flowchart shapes and Implementation shapes to design an alternate business process for a failed transaction.

  • Compensation for Transaction page. On this page you can use Flowchart shapes and Implementation shapes to design an undo process for a committed nested transaction. For more information about transactions, see Designing Transactions.

Related Topic

Handling Exceptions


Flowchart Shapes

BizTalk Orchestration Designer provides eight Flowchart shapes that are available on the Flowchart stencil. These shapes are used to describe your business process. The eight shapes on the Flowchart stencil can be used to describe the structure and meaning of XLANG schedules. XLANG is an XML-based language that describes business-process interactions.

The following table lists and describes the Flowchart shapes.

Shape name Description
Begin

The Begin shape is not available on the Flowchart stencil, it cannot be deleted, and you cannot create additional Begin shapes. The Begin shape represents the start of an XLANG schedule drawing. The Begin shape is created automatically on each Business Process, Compensation for Transaction, and On Failure of Transaction page. The Begin shape that appears on the Business Process page has configurable properties. The Begin shapes that appear on the Compensation for Transaction page and the On Failure of Transaction page do not have configurable properties. You cannot enclose a Begin shape within a transaction. The business process sequence must flow from the Begin shape to the first Flowchart shape in your drawing.
Action

The Action shape represents a process that receives a message from a port or sends a message to a port. The send or receive action can be synchronous or asynchronous, depending on the component or implementation to which the port is bound.
Decision

The Decision shape represents a process that evaluates one or more rules sequentially.

This shape has one inbound flow and one or more outbound flows. Each outbound flow is associated with a rule that evaluates to TRUE or FALSE. The first rule that evaluates to TRUE determines which outbound flow is followed in the business process. The sequence of the business process follows the flow from the first rule that evaluates to TRUE. If no rules evaluate to TRUE, the Else flow is followed.

The Decision shape must contain at least one rule. Each rule must contain a script expression.
While

The While shape contains one rule and represents a process that can be repeated. If the rule evaluates to TRUE, the flow from the rule is followed to completion and then it repeats. If the rule evaluates to FALSE, the Continue flow is followed. When the business process sequence flows from a rule in a While shape, the sequence must conclude in a single End shape.

You can also configure the preservation of state for a while loop. By right-clicking a While shape and clicking Properties, you can display the While Properties dialog box. In the State persistence area, you can choose Yes to save the messages used in each loop iteration as XLANG schedule state. If the while loop is part of a transaction that fails, an On Failure of Transaction or Compensation for Transaction page will be called for each completed loop iteration. If you choose No, only messages used in the latest loop iteration will be saved as XLANG schedule state. If the while loop is part of a transaction that fails, an On Failure of Transaction or Compensation for Transaction page will be called only once.

When a business process sequence flows to a While shape that is within a nested transaction that fails, the messages and ports that have been created on the On Failure of Transaction or Compensation for Transaction page for the nested transaction will not be available to the On Failure of Transaction page for the outer transaction. Design the On Failure or Compensation code to force the collected messages to flow normally out of the nested transaction.
Fork

The Fork shape introduces concurrency into a business process. One flow can enter a fork, and as many as 64 flows can leave a fork. Each flow that leaves a fork is executed concurrently. All business process sequences that flow from a single Fork shape must connect to a single Join shape or terminate in an End shape.
Join

The Join shape synchronizes concurrent flows in a business process. As many as 64 flows can enter a Join shape, but only one flow leaves a Join shape. The logical operators AND and OR are used to determine how to synchronize the flows. You can set the following Join properties:
  • OR. Enables the first flow that arrives to continue. The other flows continue to execute.

  • AND. Synchronizes all incoming flows before the outbound flow can continue.
Transaction

The Transaction shape represents a collection of actions that are either all executed, or else none are. There are three types of transactions:
  • Short-lived transactions

  • Long-running transactions

  • Timed transactions that are long-running

Transactions are used to make an application more reliable and to simplify error handling in large applications.

The Transaction shape is limited to a single path in, and a single path out. The Transaction shape cannot contain End shapes. Long-running transactions can contain nested transactions; however, short-lived transactions cannot contain nested transactions. Transaction retry attempts are permitted only for short-lived transactions. If you enclose part of your business process within a short-lived Transaction shape, you can configure the transaction Retry count property. If the short-lived transaction fails, it is retried for the number of times that you have specified.

By defining transaction properties, you can make available either the Compensation for Transaction page (for nested transactions) or the On Failure of Transaction page. On either page, you can model the error-handling processes that are specific to the transaction.

Note

  • If the borders of an inner Transaction shape overlap with any of the borders of the outer Transaction shape, the inner transaction will not be nested. Do not allow the borders of an inner transaction to overlap with the borders of an outer transaction.
End

The End shape represents the completion of one process flow. One drawing can use multiple End shapes if the drawing includes Decision, While, or Fork shapes.
Abort

The Abort shape terminates execution within a transaction group. This enables either an On Failure of Transaction or Compensation for Transaction error-handling page, or else it retries the transaction.

Notes

  • For the Compensation for Transaction and On Failure of Transaction pages, the parameter Transaction is replaced with the name that you give to the associated transaction on the Business Process page.

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3c.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • Transaction names in single-byte character sets must be less than or equal to 16 characters in length. Transaction names in double-byte character sets must be less than or equal to 8 characters in length.

  • Actions are exempt from all naming conventions except the 32-character size limit.

  • You cannot name any of the following shapes: Abort, Begin, Decision, End, Fork, Join, and While.

  • Do not test for the existence of messages after a while loop. Testing for the system field, MessageName.[__Exists__], after a while loop always evaluates to TRUE when the path taken in the while loop does not create the message because of the decision branch taken or a transaction abort. To check for flow control, use a stateful component to note the path taken in the while loop and use this information in the stateful component outside the loop.

Related Topics

Communication Shapes

Designing Transactions

Implementation Shapes


Implementation Shapes

BizTalk Orchestration Designer provides four Implementation shapes that are available on the Implementation stencil. These shapes are used to describe the implementation technologies that are used to implement a port in a business process.

The following table lists and describes the Implementation shapes.

Shape name | Description
COM Component | The COM Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received. Drag this shape to the right side of the Separator bar to open the COM Component Binding Wizard. For more information about the COM component implementation, see Using the COM Component Shape.
Script Component | The Script Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received. Drag this shape to the right side of the Separator bar to open the Script Component Binding Wizard. For more information about the script component implementation, see Using the Script Component Shape.
Message Queuing | The Message Queuing shape represents a technology that can be used to implement a port. Message Queuing Services are used to send or receive messages. Drag this shape to the right side of the Separator bar to open the Message Queuing Binding Wizard. For more information about the Message Queuing implementation, see Using the Message Queuing Shape.
BizTalk Messaging | The BizTalk Messaging shape represents a technology that can be used to implement a port. BizTalk Messaging Services are used to send or receive messages. Drag this shape to the right side of the Separator bar to open the BizTalk Messaging Binding Wizard. For more information about the BizTalk Messaging implementation, see Using the BizTalk Messaging Shape.

Note

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3c.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.

Related Topics

Communication Shapes

Flowchart Shapes


Communication Shapes

BizTalk Orchestration Designer provides several Communication shapes that indicate the direction of the flow of data into and out of messages. BizTalk Orchestration Designer provides the Communication shapes automatically.

The Port References, Constants, and Message shapes are located on the Data page. The Data page represents the flow of data between messages used by the XLANG schedule instance while the instance is running. To design the flow of data, you can create connections between the fields within the shapes on the Data page.

The following table lists and describes the Communication shapes.

Shape name | Description
Port | Ports are named locations where messages are sent or received. Right-click the Separator bar and click Add New Port to add an unbound port. Or drag an Implementation shape to the right side of the Separator bar to add a bound port. Each port contains messages that correspond to the Message shapes that appear on the Data page. A message represents the data that is sent or received by an action. The data within a message is separated into a list of fields on the Data page.
Port References | The Port References message contains a list of all ports that are created on the Business Process page. A new reference is added to this list every time a new port is added on the Business Process page. The Port References message enables you to specify the origin of port locations. The Port References message contains one port field for every port in the business process.
Constants | The Constants message provides a way to initialize your XLANG schedule with data. To add a constant to the Constants message, double-click the Constants message, or double-click a field in the Constants message to open the Constants Message Properties dialog box.
Message | Message shapes contain a list of fields with information about the data that is sent or received in the message.

Note

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3c.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.

    • Message names cannot be the names of system fields. System fields are listed in the following table.

Each message that is defined on the Data page has additional system fields that the XLANG Scheduler Engine automatically creates and maintains for each message. These fields can be referenced for descriptive information about the message and can be used in script expressions for rules. The following table summarizes system fields that are created automatically.

System field Description
__Exists__ This field can be used to test for the existence of a message. The existence of a message is determined by whether the message has been received or sent by the XLANG Scheduler Engine.

This field is not shown within messages on the Data page. It is used only with Decision and While shapes.
__Sender__ This field contains the identity, if known, of the sender of a message.

This field is shown within messages on the Data page.
__Status__ This field contains the status returned from a COM method call on a port that is bound to a COM component. This field is shown within the messages on the Data page.

Notes

  • This system field is used only with COM component and script component implementations.

  • The status that is returned is always an HRESULT.
Document This field contains a string containing the message body that is sent or received. It always refers to an XML message.

Note

  • This system field is used only with Message Queuing and BizTalk Messaging implementations.

Important

  • Each message that is sent from an XLANG schedule instance must have the source for each field of data defined. To define the source for a field of data, a connection must point to the field either from another field in another message or from a constant.

Note

  • The compilation engine used to create an XLANG schedule validates whether a message has all of its input-only fields defined. The schedule will not compile if the input-only fields are partially defined. The arguments to a method can be input, output, or both. The compilation engine ignores the definition requirement for arguments defined as both input and output. If no inbound connections are defined for input-output fields, the schedule will compile, even though there is no definition for the data in the message.

Related Topics

Data Handling

Flowchart Shapes

Implementation Shapes


BizTalk Orchestration Designer Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Orchestration Designer. The following table is a quick reference to these shortcut keys.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server and Advanced Server Help, see "Using the keyboard to move the mouse pointer." For more information about MouseKeys in Windows 2000 Professional Help, see "Move the mouse pointer by using MouseKeys."
Press | To
ALT or F10 | Activate the menu bar.
ALT+F4 | Close the active item, or quit the program.
ALT+F7 | Cascade windows.
ALT+SPACEBAR | Display the system menu for the active item.
ALT+Underlined letter in a menu name | Display the corresponding menu.
ARROW keys | Move the selected shape in the arrow direction.
CTRL while dragging an item | Copy the selected item.
CTRL+A | Select all.
CTRL+C | Copy the selected item on the design page.
CTRL+F4 | Close the active drawing.
CTRL+I | Return the window to its actual size.
CTRL+N | New drawing.
CTRL+O | Open an existing drawing.
CTRL+P | Open the Print dialog box.
CTRL+Q | Quit the program.
CTRL+SHIFT with any of the arrow keys | Scroll.
CTRL+SHIFT, then click left mouse key | Zoom in.
CTRL+SHIFT, then click right mouse key | Zoom out.
CTRL+SHIFT+TAB | Toggle tabs of a dialog box in back-to-front order.
CTRL+TAB | Toggle tabs of a dialog box in front-to-back order.
CTRL+V | Paste the selected item on the design page.
CTRL+X | Cut the selected item on the design page.
CTRL+Y | Redo.
CTRL+Z | Undo.
DELETE | Delete the selected item on the design page.
ESC | Cancel the current task.
F1 | View the online Help.
F11 | Launch the text properties dialog box.
F8 | Align selected shapes.
LEFT ARROW | When the focus is on a tab in a dialog box, move the focus to the left.
RIGHT ARROW | When the focus is on a tab in a dialog box, move the focus to the right.
SHIFT while dragging an item | Drag the item only in a straight horizontal or vertical direction.
SHIFT+TAB | Move the focus counterclockwise in the lower window from the tab to the windows or fields below.
SPACEBAR | Toggle check boxes.
TAB | Move the focus clockwise in the lower window from the tab to the windows or fields below.
Underlined letter in a command name on an open menu | Carry out the corresponding command.


XLANG Schedules

The compiled version of an XLANG schedule drawing is an XLANG schedule, and the XLANG Scheduler Engine runs this schedule. The XLANG Scheduler Engine monitors and controls the business process described in the XLANG schedule, based on the actions, rules, and error-handling processes that are defined for the XLANG schedule.

The following topics are covered in this section:

  • XLANG Overview

  • Instance management

  • Persistence

  • Dehydration and Rehydration

  • Data Handling


XLANG Overview

XLANG is an XML-based language that describes business-process interactions. BizTalk Orchestration Designer can compile XLANG schedule drawings into XML-structured XLANG schedule files. Because XLANG is XML-based, XLANG schedules must comply with XML rules for well-formed documents and they must conform to a specification or standard schema.


Instance Management

To understand how the XLANG Scheduler Engine performs instance management, you must be aware of the distinction between an abstract definition of a business process, and multiple running instances of a business process definition. In BizTalk Orchestration Designer, you design a business process definition and save it as an XLANG schedule drawing (an .skv file). After you have created an XLANG schedule drawing, you compile it into an XLANG schedule (an .skx file). After you deploy the XLANG schedule, there are likely to be several instances of the schedule running simultaneously. Each XLANG schedule instance can have a life span that is independent of the life span of any of the other instances. When you design an application to support multiple XLANG schedule instances, you should be aware of the following issues:

  • Activating new instances of XLANG schedules when messages are received. You can design your application to activate a new XLANG schedule instance by using the COM function GetObject every time a message is received. For example, if you use an Active Server Page (ASP) to receive a message containing a purchase order or a customer support request, the ASP must use the COM function GetObject to activate an XLANG schedule.

    You can also use the BizTalk Messaging Binding Wizard to create a port binding that can serve as a named location to which messages are sent. BizTalk Server 2002 provides an automated mechanism to activate an instance of an XLANG schedule when a port that is bound to BizTalk Messaging receives a message. On the XLANG Schedule Activation Information page of the BizTalk Messaging Binding Wizard, you are prompted to confirm whether the channel has been configured in BizTalk Messaging Services to send a message to this port after the activation of a new instance of this XLANG schedule. To complete this process, you have to run the New Messaging Port Wizard in BizTalk Messaging Manager. On the Destination Application page of the New Messaging Port Wizard, specify the name of the port and the name and location of the XLANG schedule.

  • Correlating messages with XLANG schedule instances. Every instance of an XLANG schedule is assigned a globally unique identifier (GUID) by the XLANG Scheduler Engine. This instance ID can be used to correlate messages with schedule instances. Correlation can be done in the following ways:

    Using a single queue. You can use a single queue for all instances to avoid the overhead of a large number of per-instance queues. You do this by using the GUID, or instance ID, of the schedule instance. You must save the instance ID of the schedule when you send a message, retrieve it upon receiving a message, and use it to create a mechanism for correlating the incoming message with the correct schedule instance. You can do this in one of two ways:

    • Identify a message field that can be used for correlation. This field must be guaranteed to be unique. It may be a field created specifically for this purpose, or it may be a field that already exists in a document format.

      For sending, you can save the instance ID and the value of the correlation field. The pipeline component can retrieve Src_XLANG_InstanceID from the dictionary and save it, along with the correlation field value, to a local database.

      For receiving, you can write a custom component that will extract the correlation field from the incoming message, find the corresponding instance ID in the database, and use the value to set Dest_XLANG_InstanceID in the dictionary for subsequent delivery of the message to the proper instance.

    • Use the instance ID as the message label. To do this, select the Use Instance Id as Message Label box on the Message Type Information dialog box in the XML Communication Wizard, when you are binding actions and ports. For more information, see Using the XML Communication Wizard.

    Using a queue per instance. Every port on every running instance of an XLANG schedule can be uniquely addressable. This addressability enables you to have direct communication to specific ports on specific XLANG schedule instances, without having to write custom code to do the correlation for you. The first message sent by a schedule instance will likely be to a static port (a named location). When the XLANG schedule is activated, this instance sends the locations of its dynamic ports (per-instance, unique locations) to recipients that are responsible for communicating back to the ports. This corresponds to e-mail messages that are sent out with unique reply-to addresses. The following list describes dynamic binding support in each of the BizTalk Server binding technologies:

    • On the Static or Dynamic Communication page of either the COM Component Binding Wizard or Script Component Binding Wizard, if you choose Static, the XLANG Scheduler Engine will create the XLANG schedule instance of the component. If you choose Dynamic, another application must send an interface pointer or moniker (as a field in a message) prior to the instantiation of the component.

    • You also have the option of choosing No instantiation. For more information about component instantiation, see Static and Dynamic Ports.

    • On the Static or Dynamic Queue Information page of the Message Queuing Binding Wizard, if you choose Static queue and click Next, you will invoke the Queue Information page. On this page you can specify the creation of a separate, per-instance queue for every XLANG schedule instance, or you can specify the use of a single queue for all running instances.

    • On the Static or Dynamic Queue Information page of the Message Queuing Binding Wizard, if you choose Dynamic queue, another application must send the name of the queue (as a field in a message) prior to sending or receiving messages through the port.

    • On the Static or Dynamic Channel Information page of the BizTalk Messaging Binding Wizard, you can choose to provide a specific channel name, or indicate that port configuration information will be used by BizTalk Messaging Services to identify the correct channel at run time. For more information about message exchange, see Integrating BizTalk Services.
  • Scaling the application. Any XLANG schedule instances that do not need to be in memory should be dehydrated. An XLANG schedule instance might not need to be in memory when an XLANG schedule instance is waiting for the arrival of a message.

Notes

  • All Implementation shapes display a shadow to indicate that the location will be bound dynamically and defined at run time.

  • Any child instance forked from a parent instance has a unique instance ID, separate from that of its parent. Each child instance within a while loop (on each pass through the loop) likewise has its own unique instance ID.

Related Topics

Data Handling

Dehydration and Rehydration

Managing Session State

Persistence

XLANG Schedule Correlation


Persistence

The XLANG Scheduler Engine stores the following information in the persistence database:

  • The structure of XLANG schedules.

  • The progress of activated XLANG schedule instances.

  • Messages that are sent or received while an XLANG schedule instance is running.

The XLANG Scheduler Engine persists information to enable the following scenarios:

  • To enable the dehydration and rehydration of long-running schedules. The system might fail during a long-running transaction. When the system is running again, the XLANG Scheduler Engine refers to the persistence database to determine where to resume the schedule.

  • To restore the state of a schedule instance when a transaction fails. The system might fail during a transaction, causing the transaction to abort. The XLANG Scheduler Engine refers to the persistence database to determine where to resume the schedule.

  • To support the debugging and monitoring of running schedules. Debugging and monitoring tools can query the persistence database to provide information about the progress of schedule instances.

Support for persisting the state of an XLANG schedule before the start of a transaction, and after the completion of a transaction, provides durability, ensuring that all committed modifications are permanently in place in the system. This also enables retries of a transaction if a failure occurs. The state of a running schedule instance is persisted under the following circumstances:

  • At the beginning of a transaction. When the business process sequence flows to the start of a transaction, the transaction retry count must be updated in the persistence database. This enables the XLANG Scheduler Engine to track the retry count if the system fails during the transaction.

  • At the end of a transaction. When the business process sequence flows out of a transaction, the schedule state must be updated to enable rollback, if necessary. This update occurs in the context of the transaction to ensure that database persistence is atomic.

Related Topics

Dehydration and Rehydration

Instance Management

Managing Session State


Dehydration and Rehydration

If multiple instances of an XLANG schedule are running simultaneously over a long period of time, it can become impractical to allow all of them to remain in memory. The XLANG Scheduler Engine provides a dehydration/rehydration infrastructure to address this problem.

When an XLANG schedule instance is expected to wait for a message for an extended period of time, and no other activity is occurring within the schedule, the XLANG Scheduler Engine can dehydrate the XLANG schedule instance. Dehydrating an XLANG schedule instance consists of persisting all the instance-specific state to the persistence database and removing the instance from memory. When a message arrives at a port address for the dehydrated XLANG schedule instance, the instance is rehydrated. Rehydrating an XLANG schedule instance consists of restoring the instance from the database to memory.

An XLANG schedule instance remains dehydrated until it is either rehydrated or explicitly terminated by an administrator. This enables a business process to run reliably for an extended time period.

The XLANG Scheduler Engine can use a latency setting to determine an amount of time that an action can remain inactive before the XLANG schedule instance is dehydrated to the persistence database. The XLANG Scheduler Engine can use this latency setting to dehydrate the XLANG schedule instance to the persistence database, and then rehydrate it later when the message arrives. However, there are several situations during which the latency setting does not cause a schedule to be dehydrated, including:

  • The schedule instance is not in a quiescent state. This can occur when actions are being performed on one of the current process flows in the XLANG schedule instance. All process flows in the schedule instance must be in the same state before the XLANG Scheduler Engine will dehydrate the XLANG schedule instance. The latency time for all pending actions must exceed a certain threshold before dehydration is performed.

  • There are pending DTC-style transactions. The XLANG Scheduler Engine will not dehydrate the schedule when it is running a DTC-style transaction, because DTC-style transactions are typically short-lived.

  • There are live ports in the instance that cannot be persisted. A live port is a port object or a port that has been implemented and that might be used later in the schedule instance. The lifetime of a port is an important issue during the execution of a schedule instance. Ports are bound to implementation technologies, such as COM interfaces. If the implementation technology that a port is bound to cannot be persisted, and if the implementation technology holds state information that is reused later, the instance cannot be dehydrated and then rehydrated. If the persistence database fails and then runs again later, the state information will be lost and schedule instance execution cannot be resumed from the state of the schedule instance when it was last dehydrated.

When the XLANG Scheduler Engine is shut down, as much information as possible is saved to the persistence database, including all information that is not in a transactional context.

Related Topics

Instance Management

Managing Session State

Persistence

Using the Method Communication Wizard

Using the XML Communication Wizard


Data Handling

In XLANG, all data is contained within a set of uniquely named messages. New data enters an XLANG schedule instance when a message is received by an action.

Every XLANG schedule drawing has one Data page. On the Data page you can describe the data flow within an XLANG schedule. To indicate that data within one message field flows into another message field, draw an arrow from the source message field to the destination message field.

With the exception of the Constants message, none of the message fields within the messages on the Data page will initially contain a value. The Constants message is initialized with the values that are specified on the Data page. It is initialized automatically for each new XLANG schedule instance. For more information about using constants, see The Constants Message.

The values of the other displayed messages are set when each message is sent or received in the XLANG schedule instance. A message can be received by more than one action. Every time a message is received, the values for that message are overwritten. The flow of data into the received message will not be used to set the values for a different received message, even if the message is sent out at another point in the XLANG schedule. Messages that are exclusively sent out rely on the data flow that is displayed on the Data page to set their message fields. A schedule will not compile unless all of the fields are specified for all of the messages that have been sent.

When a field on the Data page comes from an XPath that points to an optional node in the XML schema, use the following guidelines:

  • For received messages when the optional node exists. If this message is received, and the optional node exists in the XML document, the XPath field stores the node value.

  • For received messages when the optional node does not exist. If this message is received, and the optional node does not exist, the XPath field stores a null value. You need to use a Decision rule with the Microsoft® Visual Basic® Scripting Edition (VBScript) expression IsNull (Message.Field) on this field to determine if the received message contains the optional node. If you do not test for the existence of a value, and this field provides data flow into another message that is sent, an error occurs when the XLANG Scheduler Engine tries to create the message to be sent.

  • For sent messages when the optional node exists. If this message (with the XPath node pointing to an optional XML node) is being sent, the XLANG Scheduler Engine relies on data flow to create the message. If the node exists in the Document field of the message, the XLANG Scheduler Engine overwrites it with the value of the XPath.

  • For sent messages when the optional node does not exist. If this message (with the XPath node pointing to an optional XML node) is being sent, the XLANG Scheduler Engine relies on data flow to create the message. If the node does not exist in the provided Document field, the XLANG Scheduler Engine does not create the node to overwrite. This causes an error.

For messages that will be received from or sent to a message queue, use the following guidelines:

  • For received messages. If an action will receive a non-XML message from a message queue, you must select Receive string messages from a queue on the XML Translation Information page of the XML Communication Wizard. In this configuration, the Message shape on the Data page will display a new StringData field. This StringData field will contain the non-XML message received from the queue. The Document field on the message will contain the StringData field, surrounded by the XLANG Scheduler Engine standard XML wrapper.

  • For sent messages. If an action will send a non-XML message to a message queue, you must select Send messages to the queue as a string on the XML Translation Information page of the XML Communication Wizard. In this configuration, the Message shape on the Data page will display a new StringData field. To complete this configuration, you must create a new constant (containing the XLANG Scheduler Engine standard XML wrapper) in the Constants message on the Data page. The name of this constant is irrelevant, but the data type must be string, and the value of the constant must be <?xml version="1.0" ?> <StringData> </StringData>. After you have created this new constant, you must draw a data flow connection from the new constant on the Constants message to the Document field in the Message shape. You must also draw a data flow connection from the field containing the non-XML string to the new StringData field in the Message shape.

Notes

  • The direction of data flow is independent of the direction of message flow. Message flow indicates if a message is sent or received.

  • If you want to enable the XLANG schedule to receive data by using a method call without instantiating the component, select No instantiation on the Static or Dynamic Communication page of either the COM Component Binding Wizard or the Script Component Binding Wizard. If you select No instantiation, the component is not instantiated, and no code for the method call is executed. Instead, when the XLANG schedule intercepts the method request information, it returns this information as the response. The method call is circumvented.

  • If a message is used only within the body of a while loop, the message values are not initialized on every iteration of the loop. If a message is used both inside and outside the body of a while loop, the message values are retained throughout each iteration of the loop. The message values might also be retained before and after the business process sequence flows to the While shape.

  • If a message that is initialized within the compensation process or the failure process of a transaction within a while loop, the message values will not be available outside the loop.

  • If a field within an XML message (including the constants message) with a data type of char provides data flow into a method message field, the field will be converted to an integer for the method. If the method message field has a data type of string, the string will contain the integer value; it will not contain the character. If you encounter this problem, and the source field is part of the constants message, change the data type of the constants field to string. If the source field is part of an XML message, you will have to use a component to cast the char data type to a string.

The following topics are covered in this section:

  • The Data Page

  • The Constants Message

  • The Port References Message

  • Field Data Types

  • System Fields

  • Node Path Fields


The Data Page

Every XLANG schedule drawing has a Data page. The Data page displays:

  • One Message shape for every message in the XLANG schedule.

  • One Constants message.

  • One Port References message containing a port field for each port within the XLANG schedule drawing.

  • Diagrammatic connections showing the flow of data between the message fields.

Messages consist of a set of uniquely named fields, each containing one data item of a specific data type. Every message in the XLANG schedule is displayed on the Data page as a table. Each table displays the name of the message and a listing of field names and their corresponding data types. System fields that do not require data flow are displayed with a yellow background. User fields, and system fields that do require data flow, are displayed with a white background.

Connections on the Data page point from the right side of a source message field to the left side of a destination message field. This connection indicates that the source message field will provide the data for the destination message field. At run time, the XLANG Scheduler Engine will copy the data from the source message field into the destination message field when the destination message has to be created. If the source message has not arrived yet, a run-time error will occur.

Notes

  • The following data types are not supported on the Data page:
    • BinHex

    • BinBase64

    • I8

    • UI8

If you have a node in an XML document of type BinHex, BinBase64, I8, or UI8, and you specify that the node should be brought into the scope of the XLANG Scheduler Engine on the Data page, using the XPath to this node, the node will be converted to a string.

  • There is a 100-character limit for all field names in XLANG schedules.

Related Topics

The Constants Message

Data Handling

Field Data Types

Node Path Fields

The Port References Message

System Fields


The Constants Message

You can use the Constants message to initialize an XLANG schedule instance with data. Within the XLANG Scheduler Engine, the Constants message performs a unique function; it is neither sent nor received. It is initialized automatically for each new XLANG schedule instance. To add a constant to the Constants message, double-click the Constants message, or double-click a field in the Constants message to open the Constants Message Properties dialog box. Click Add in the Constants Message Properties dialog box to open the Constant Properties dialog box. In the Constant Properties dialog box, you can name the constant, choose a data type for the constant, and assign a value to the constant.

International Issue

  • XML does not handle Windows Locale settings for date formatting. If you want to assign a date in a localized format for a constant, set the constant data type to string. If this constant provides data to a field with a date data type, the XLANG Scheduler Engine will translate the string to a date, adhering to the localized format.

Related Topics

Data Handling

The Data Page

Field Data Types

Node Path Fields

The Port References Message

System Fields


The Port References Message

The Port References message contains a list of all ports that are created on the Business Process page. A new reference is added to this list every time a new port is added on the Business Process page. The Port References message enables you to specify the origin of port locations. The Port References message contains one port field for every port in the XLANG schedule drawing.

There are scenarios in which ports in an XLANG schedule are not known at design time. This can occur if the destination or origin of messages is determined from the contents of other messages. For example, a business process might describe a situation in which an action must respond to a message with an acknowledgement to the originating trading partner. In this example, the message that is received will typically have a reply-to-address field that contains the originating address of the message. The XLANG schedule must be able to correlate the contents of the reply-to-address field to the destination address of the acknowledgement message. You can use the Port References message and an acknowledgement message on the Data page to implement this scenario. For more information about message exchange, see Integrating BizTalk Services.

Related Topics

The Constants Message

Data Handling

Field Data Types

Node Path Fields

System Fields


Field Data Types

BizTalk Orchestration Designer displays all data types with their XML data type name. The following table lists the OLE Automation, Visual Basic, and C program equivalents of the displayed XML data type names.

XML UI View | OLE Automation | Visual Basic | C
simple types |  |  |
boolean | VT_BOOL | Boolean | VARIANT_BOOL
string | VT_BSTR | String | BSTR
cy | VT_CY | Currency | CURRENCY
date | VT_DATE | Date | DATE
dispatch | VT_DISPATCH | Object | IDispatch
error | VT_ERROR |  | SCODE
i1 | VT_I1 |  | signed char
i2 | VT_I2 | Integer | SHORT
i4 | VT_I4 | Long | LONG
int | VT_INT |  | INT
r4 | VT_R4 | Single | FLOAT
r8 | VT_R8 | Double | DOUBLE
ui1 | VT_UI1 | Byte | BYTE
ui2 | VT_UI2 |  | USHORT
ui4 | VT_UI4 |  | ULONG
uint | VT_UINT |  | UINT
unknown | VT_UNKNOWN | Object | IUnknown
variant | VT_VARIANT | Variant | VARIANT

Related Topics

The Constants Message

Data Handling

The Data Page

Node Path Fields

The Port References Message

System Fields


System Fields

Each message can also contain a set of system fields that are automatically created by the XLANG Scheduler Engine.

System field name | When is this system field displayed? | Description
__Status__ | When the message is being received from a port bound to a COM or Script binding. | The HRESULT of the method call.
__Sender__ | When the message is sent to or received from any port. | This is a string containing the SenderID provided by Message Queuing or COM when a message is received. When this message is sent, the value is NULL.
Document | When the message is sent or received from a port that is bound to Message Queuing or BizTalk Messaging. | A string containing the message body that is sent or received.

Related Topics

The Constants Message

Data Handling

Field Data Types

Node Path Fields

The Port References Message


Node Path Fields

When a port bound to Message Queuing or BizTalk Messaging receives an XML document, you can bring specific document nodes into the data scope of the XLANG Scheduler Engine. If no specific nodes are selected, the XLANG Scheduler Engine will treat the XML document as an opaque string that is carried within the document system field.

You can bring document nodes into the data scope of the XLANG Scheduler Engine by using the Message Specification page in the XML Communication Wizard. When you provide an XML specification, the Add and Remove buttons are enabled.

Related Topics

The Constants Message

Data Handling

Field Data Types

The Port References Message

System Fields

Using the XML Communication Wizard


Creating XLANG Schedule Drawings

There are five tasks you must perform when you design an XLANG schedule:

  • Draw a representation of the business process that the XLANG schedule will run. Use Flowchart shapes to describe the flow of the business process on the left side of the design page. Your primary business process is drawn on the Business Process page. Alternate processes are drawn on the Compensation for Transaction and On Failure of Transaction pages.

  • Define rules for the branching decisions and repeated processes that occur within the business process; define concurrent processes; and design the transactions and subordinate transactions required in the business process.

  • Create the port implementations that the business process requires. There are four implementation technologies available: COM components, Windows Script Components, Message Queuing Services, and BizTalk Messaging Services.

  • Define the flow of data between messages. All flow of data between messages is drawn on the Data page.

  • Draw any necessary business processes for transactions that fail. Alternate business processes are drawn on the Compensation for Transaction and On Failure of Transaction pages.

Note

  • You can add Flowchart and Implementation shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. These shapes are not available on the Data page.

The following topics are covered in this section:

  • Designing Business Processes

  • Handling Exceptions

  • Implementing Business Processes


Designing Business Processes

In BizTalk Orchestration Designer, the left side of the Business Process page is the area in which you can design business processes. A Separator bar divides the Business Process page into a business process design area on the left side and an implementation area on the right side.

The following topics are covered in this section:

  • Designing Actions

  • Designing Rules

  • Designing Concurrency

  • Designing Transactions


Designing Actions

The business process sequence must flow from the Begin shape to the first Flowchart shape in your XLANG schedule drawing. Typically, the first Flowchart shape in your XLANG schedule drawing is an Action shape.

There are two configurable properties for a Begin shape. In the Begin Properties dialog box, you can configure the Transaction Model property to determine if Transaction shapes are supported within an XLANG schedule instance, or if the XLANG schedule is activated from within a transactional COM component. The first option enables support for Transaction shapes; the second option disables support for Transaction shapes.

In the Begin Properties dialog box, you can also configure the Transaction Activation property and the XLANG identity property. For more information about transaction activation, see Designing Transactions.

XLANG identity is a read-only property. It contains a globally unique identifier (GUID) that is used to correlate a version of the XLANG schedule drawing with the XLANG schedule that is generated by it. The GUID is automatically generated when a new drawing is created, and a new GUID is generated whenever the XLANG schedule drawing is changed.

The only configurable property for an Action shape is the name of the action. The name of the action cannot be longer than 32 characters. Action names have no affect on the behavior of the XLANG schedule.

Related Topics

Designing Concurrency

Designing Rules

Designing Transactions

Flowchart Shapes


Designing Rules

Rules are Microsoft Visual Basic Scripting Edition (VBScript) expressions that are used by Decision and While shapes. Rules can include:

  • Intrinsic VBScript expressions, such as Date and Time.

  • Expressions that evaluate data within a message field.

  • Expressions that can determine whether a message exists.

A rule contains the following properties that define the behavior of the shape:

  • Rule name. A required property that is displayed on the XLANG schedule drawing within the shape that uses the rule. The rule name uniquely identifies the rule. A single, uniquely named rule can be used in multiple Decision and While shapes. The width of the Decision or While shape that uses the rule is determined by the rule with the longest name that is contained within the shape.

  • Rule description. An optional property. It is a description of the rule.

  • Script expression. A required VBScript expression that refers to data contained in messages. The expression must evaluate to either TRUE or FALSE.

When you design an XLANG schedule drawing, you create the rules and provide name and rule descriptions. When you add Implementation shapes to the drawing, you add script expressions.

Notes

  • The Script expression property requirement is enforced only when compiling the XLANG schedule drawing into an XLANG schedule.

  • There is a message field called the __Exists__ field that is not shown within messages on the Data page. This field can be used to test for the existence of a message. The existence of a message is determined by whether the message has been received or defined by the XLANG Scheduler Engine.

Related Topics

Create Rules

Designing Actions

Designing Concurrency

Designing Transactions

Flowchart Shapes

Set Decision Conditions


Designing Concurrency

BizTalk Orchestration Designer supports concurrent actions. The Fork and Join shapes are used to implement concurrent process flows within an XLANG schedule. You can use the Fork shape to create concurrent process flows, and you can use the Join shape to synchronize any concurrent process flows that are not terminated by an End shape.

Join properties

The Join shape has two properties that you can set. These properties represent the following logical operators:

  • AND. The XLANG schedule waits until all process flows reach the join before it continues to the next action in the business process.

  • OR. The XLANG schedule waits for the first process flow that reaches the join, and then it continues to the next action in the business process.

    Actions in the other branches of the fork complete their processes; however, the OR join does not wait for them to be completed. If the process flow that exits an OR join includes an action that requires data flow from a branch that enters the OR join and that has not completed its action by the time the action that exits the join is executed, an error occurs.

Valid fork and join process flows

Observe the following guidelines when designing concurrent flows in a business process:

  • All forked flows must either terminate with an End shape or be synchronized into a single flow by using a Join shape.

  • Actions within forked flows cannot communicate with each other. For example, an action in one branch cannot send a message to a queue from which an action on another branch is waiting to receive a message.

    Caution

    • If you incorrectly design your XLANG schedule drawing to support communication between actions in different branches, the XLANG schedule instance might fail at run time; however, an error message will not be displayed.
  • You cannot use a join to synchronize flows from more than one fork. The Join shape can be used only to synchronize flows from a matching fork. There is a one-to-one correspondence between the use of the Fork shape and the Join shape.

    The following illustration shows two forks that are used to create concurrent flows, and a single join that is used in an attempt to synchronize these flows. This connection is not legal. If you attempt this type of connection, you will receive an error message when you compile the XLANG schedule.

    Concurrent flows joined illegally

    The following two illustrations provide two examples of legal joins.

    In following illustration shows two forks that are matched with two joins. The second fork and join pair are nested within the first fork and join pair.

    Concurrent flows joined legally

    The following illustration shows two forks that are matched with two joins. The second fork and join pair are nested within the first fork and join pair. Note that even though one concurrent flow within the second fork and join pair is terminated by an End shape, the other concurrent flow must still be synchronized by a matching join before its flow can be synchronized with the concurrent flow from the first fork and join pair.

    Concurrent flows joined legally

  • When you synchronize multiple concurrent flows with an OR join, each process flow that enters the join can contain only one action. If a flow contains more than one action, the flow is not legal.

    The following illustration shows an OR join that synchronizes multiple concurrent flows. Each flow contains only one action.

    Concurrent flows joined legally

Important

  • Actions in different branches of a fork cannot communicate with each other. For example, an action in one branch cannot send a message to a queue from which an action on another branch is waiting to receive a message. If you incorrectly design your XLANG schedule drawing to support communication of any kind between actions in different branches, the XLANG schedule instance might fail at run time; however, an error will not be displayed.

Related Topics

Designing Actions

Designing Rules

Designing Transactions

Flowchart Shapes

Set Concurrency Properties


Designing Transactions

BizTalk Orchestration Designer provides a transactional programming model, including error handling and recovery from failed transactions. You can configure Transaction shapes to create two additional types of pages in BizTalk Orchestration Designer: the On Failure of Transaction page and the Compensation for Transaction page. These two pages are used to enable business processes to recover from unsuccessful transactions. On Failure of Transaction and Compensation for Transaction pages can contain Transaction shapes that reference additional On Failure of Transaction and Compensation for Transaction pages. The On Failure of Transaction and Compensation for Transaction pages can use the same Port shapes and Implementation shapes that are displayed on the Business Process page.

The short-lived transactions that you design within BizTalk Orchestration Designer have the four ACID attributes. ACID is an acronym that is made up of the following properties:

  • Atomicity. A transaction represents an atomic unit of work. Either all modifications within a transaction are performed, or none of the modifications are performed.

  • Consistency. When committed, a transaction must preserve the integrity of the data within the system. If a transaction performs a data modification on a database that was internally consistent before the transaction started, the database must still be internally consistent when the transaction is committed. Ensuring this property is largely the responsibility of the application developer.

  • Isolation. Modifications made by concurrent transactions must be isolated from the modifications made by other concurrent transactions. Isolated transactions that run concurrently perform modifications that preserve internal database consistency exactly as they would if the transactions were run serially.

  • Durability. After a transaction has committed, all modifications are permanently in place in the system by default. The modifications persist even if a system failure occurs.

In contrast, long-running transactions sacrifice isolation for the ability to handle operations that require an extended period of time to complete.

Notes

  • To test for the outcome of a transaction, you should use a message created in the transaction on-failure process. You should not test for a transaction outcome by testing for the existence of a message — which may or may not have been modified — used in the transaction.

  • When using COM+ Bring Your Own Transaction (BYOT) functionality with COM components for the XLANG Scheduler Engine, create a wrapper component that is written and installed into a COM+ application. All method calls to the component will be forwarded from the wrapper component. If a BYOT component is imported into a COM+ application, it will fail to start traditional COM components, because the component that provides the functionality is registered as a traditional COM component, not a COM+ application.

The following topics are covered in this section:

  • Transaction Properties for an XLANG Schedule Drawing

  • Transaction Properties for Specific Transaction Shapes

  • Transaction Properties for a Port Implementation

  • Long-Running Transactions

  • Short-Lived Transactions

Related Topics

Designing Actions

Designing Concurrency

Designing Rules

Flowchart Shapes

Set Transaction Properties


Transaction Properties for an XLANG Schedule Drawing

By right-clicking the Begin shape on the Business Process page and clicking Properties, you can display the Begin Properties dialog box. In the Begin Properties dialog box, you can configure the following properties:

  • Transaction Model. The default setting for this property is Include transactions within the schedule.
    • Choose Include transactions within the schedule if you are planning to enclose a collection of grouped actions in a Transaction shape within your XLANG schedule drawing. By choosing this option, you disable the Transaction Activation property.

    • Choose Treat the XLANG schedule as a COM+ component if you want a COM+ component to activate your XLANG schedule within its COM+ transactional context. If you choose this option, you will not be able to include transactions within your XLANG schedule drawing, and your use of the Fork shape to implement concurrency should be restricted. If you do use the Fork shape, all actions containing calls to COM+ components should be restricted to a single outbound branch. This restriction does not apply if the actions in your XLANG schedule drawing contain calls to COM components. Also, all transactional changes should be performed on a single outbound branch.

      By choosing this option, you enable the Transaction Activation property.

  • Transaction Activation. The default setting for this property is Not Supported.
    • Not Supported. This selection specifies that the XLANG schedule does not support transactions.

    • Supported. This selection specifies that the XLANG schedule might participate in a COM+ transaction.

    • Required. This selection specifies that the XLANG schedule requires a COM+ transaction.

    • Requires New. This selection specifies that the XLANG schedule must participate in a new transaction. If this setting is enabled, the XLANG Scheduler Engine automatically initiates a new transaction that is distinct from the transaction of the caller.
  • XLANG Identity. For information about the XLANG identity property, see Flowchart Shapes.

Related Topics

Designing Transactions

Long-Running Transactions

Short-Lived Transactions

Transaction Properties for a Port Implementation

Transaction Properties for Specific Transaction Shapes


Transaction Properties for Specific Transaction Shapes

By right-clicking a Transaction shape on the Business Process page and clicking Properties, you can display the Transaction Properties dialog box. In the Transaction Properties dialog box, you can configure the following properties:

  • Type. This property determines the type of transaction that is used for the selected Transaction shape. The default setting for this property is Short-lived, DTC-style.
    • Choose Short-lived, DTC-style if you want the transaction to group a collection of actions that are performed as a single logical unit of work exhibiting the four properties of an ACID transaction. For more information about ACID transactions, see Designing Transactions. Short-lived, DTC-style transactions are shaded gray on the design page. This option is available for nested transactions and stand-alone transactions. You cannot choose this option for an outer transaction that contains a nested transaction.

    • Choose Long-Running if you want the transaction to group a collection of actions that send and receive messages over an indefinite period of time. You can also configure a Long-Running transaction to group a collection of nested transactions; however, transactions are limited to one level of nesting. Long-Running transactions are shaded yellow on the design page. This option is available for all transactions.

    • Choose Timed if you want the Long-Running transaction to abort if it has not completed in a specified amount of time. Timed transactions are shaded blue on the design page. The Timed option is available for all transactions.
  • Persist Schedule State. This property determines whether or not the schedule state is saved to the Orchestration Persistence database. This option is available for Timed and Long-running transactions. If you are not concerned about persisting state information, you might get greater throughput by turning off this property.

  • Timeout. This property determines the amount of time (in seconds) that the transaction will be allowed to run before it aborts. This option is available for Timed and Short-lived, DTC-style transactions.

  • Retry Count. This property determines the number of times a process within a Short-lived, DTC-style transaction will be run if the process within the transaction does not complete. For each retry, the state of the application is reset to the starting point of the process within the transaction.

  • Backoff Time. This property determines the interval between each attempt to retry the transaction. The backoff time is used with the retry count value to determine how long to wait before the next transaction retry. The backoff value is exponential. A backoff value of 2 seconds results in intervals of 2, 4, 8, 16 seconds, and so on between each retry. The formula is B**R (B raised to the power of R), where B=backoff time and R=current retry count. If the backoff time of a specific transaction retry attempt is greater than 180 seconds, the XLANG schedule instance will be dehydrated to the persistence database immediately.

  • Isolation Level. The isolation level determines the degree to which data within concurrent transactions is accessible to each other. This option is available only for Short-lived, DTC-style transactions. You should choose:
    • Serializable to prevent concurrent transactions from making data modifications until the selected transaction is complete. This is the most restrictive of the four isolation levels.

    • Read Uncommitted to allow concurrent transactions to make data modifications before the selected transaction is complete. This is the least restrictive of the four isolation levels.

    • Read Committed to prevent the selected transaction from accessing data modifications in concurrent transactions until they are committed. This option is the Microsoft® SQL Server™ default setting.

    • Repeatable Read to require read locks until the selected transaction is complete.
  • On Failure. Click Add Code, select the Enabled check box, and then click OK if you want to enable the On Failure of Transaction page. You will then be able to use the On Failure of Transaction page to design an alternate business process to handle the failure of the selected transaction. This option is available for all transactions.

  • Compensation. Click Add Code, select the Enabled check box, and then click OK if you want to enable the Compensation for Transaction page. You will then be able to use the Compensation for Transaction page to design an alternate business process to undo the logical unit of work that was performed in a nested transaction that has already committed. This option is available only for nested transactions.

Note

  • Aborting a nested transaction does not automatically cause an abort of the outer transaction. This enables you to design an outer transaction that can recover from the failure of a nested transaction. However, the failure of a nested transaction can cause the failure of an outer transaction if the nested transaction's On Failure of Transaction page or Compensation for Transaction page is designed to abort the outer transaction.

Related Topics

Designing Transactions

Long-Running Transactions

Short-Lived Transactions

Transaction Properties for an XLANG Schedule Drawing

Transaction Properties for a Port Implementation


Transaction Properties for a Port Implementation

You can configure transaction properties for COM components and Windows Script components on the Advanced Port Properties pages of the COM Component Binding Wizard and the Script Component Binding Wizard. The Advanced Port Properties page provides an option to abort the current transaction when an error is returned from a method in a component. On the Advanced Port Properties page, you can configure the following transactional properties:

  • Transaction support. The Transaction support property specifies the degree to which your component will require, support, or ignore transactions.
    • Disabled. This selection specifies that the component will ignore COM transaction management.

    • Not Supported. This selection specifies that the component will not participate in a transaction, or propagate the transactions of other components.

    • Supported. This selection specifies that if a transaction contains an action that is connected to the port to which the component is bound, the component will be included in the transaction. Otherwise, the component will not have a transaction.

    • Required. This selection specifies that if a transaction contains an action that is connected to the port to which the component is bound, the component will be included in the transaction. If there is no transaction containing an action that is connected to the port to which the component is bound, a new transaction will be created for the component.

    • Requires new. This selection specifies that a new transaction will always be created for the component.

Important

  • BizTalk Orchestration Designer relies on the transactional behavior of the implementation technologies that are utilized in an XLANG schedule drawing. It does not provide or impose transactional behavior on a business process if the XLANG schedule drawing contains a Transaction shape. If a COM component, message queue, or script component is not transactional, the data manipulated by the XLANG schedule drawing will not be modified in a transactional manner.

Notes

  • When you set the Transaction Model property to treat the XLANG schedule as a COM+ component, do not use Transaction shapes in the XLANG schedule drawing. If you use Transaction shapes, and then attempt to compile the XLANG schedule drawing into an XLANG schedule, the compile process will not work. You must remove all Transaction shapes from the XLANG schedule drawing before compiling.

  • If the use of a COM component occurs in multiple transactions, the COM component must either hold no state or hold state and support persistence.

  • If multiple actions communicate with a port bound to a COM or script component, and these actions can be found within multiple transactions that are not nested within each other, the component instances will be destroyed and instantiated again prior to each new transactional context. If the component holds state and supports persistence, the reactivation will restore the state. If the component holds state and does not support persistence, the state will be lost. If the component was instantiated by another application, the XLANG Scheduler Engine will be able to reactivate the component only if it is persistable. If the component was instantiated by another application and cannot be persisted, the XLANG Scheduler Engine will not be able to instantiate the component again, and the XLANG schedule will fail with an error.

Related Topics

Designing Transactions

Long-Running Transactions

Short-Lived Transactions

Transaction Properties for an XLANG Schedule Drawing

Transaction Properties for Specific Transaction Shapes


Long-Running Transactions

Long-running transactions do not support isolation, one of the four ACID attributes described in Designing Transactions. The data within a long-running transaction is not locked; other processes or applications can modify the data. If your data must be consistent, you should use ACID transactions exclusively. However, because ACID transactions in a long latency environment will cause severe scalability problems, XLANG schedule drawings support long-running transactions. Long-running transactions enable you to avoid having to lock databases for extended periods of time. During a long-running transaction, messages are sent and received over an indefinite period of time. Depending on the requirements of the business process that your XLANG schedule drawing describes, you can enclose an entire business process (with the exception of the Begin shape and an End shape) within a long-running transaction.

Typically, a long-running transaction will contain several nested short-lived transactions. For example, in a simple wire transfer scenario, a long-running transaction might contain the following actions within a nested short-lived transaction:

  • Withdraw money from a bank account.

  • Initiate the wire transfer process.

The following illustration shows Send money, a short-lived transaction that is nested within a long-running transaction called Wire transfer. The nested transaction contains the two actions in the simple wire transfer scenario. When the Initiate the wire transfer action has completed, the business process sequence flows out of the nested transaction. When this happens, the nested transaction is committed; the money has been withdrawn from a bank account and sent to a destination. At this point, the business process sequence flows to the Wait for acknowledgement action in the outer transaction.

In this scenario, the Wire transfer transaction has been configured as a Timed transaction. If the sender has not received an acknowledgement of receipt of the money within the specified amount of time, the outer transaction will abort. When this happens, the business process sequence flows to the Compensation for Send money page for the nested transaction. Because the nested transaction has already committed, the alternate business process must describe actions that can be performed to credit the sender's account. When the business process described in the Compensation for Send money page has been performed, the business process sequence flows to the On Failure of Wire transfer page for the outer transaction. This page must contain a business process that describes exception handling for the outer transaction. In this case, the business process might be to send follow-up e-mail to inform the participants of the status of the transfer.

Related Topics

Designing Transactions

Flowchart Shapes

Short-Lived Transactions


Short-Lived Transactions

A short-lived transaction is a collection of grouped actions that are performed as a single logical unit of work. This logical unit of work exhibits the four properties of an ACID transaction. For more information about ACID transactions, see Designing Transactions.

Related Topics

Designing Transactions

Flowchart Shapes

Long-Running Transactions


Handling Exceptions

The XLANG Scheduler Engine can trap system errors. BizTalk Orchestration Designer enables you to design XLANG schedules that will react to XLANG schedule errors at run time. If you enclose part of a business process within a Transaction shape, you can design an alternate business process that will run if an error is encountered or if a requirement is not met.

The following topics are covered in this section:

  • System Errors

  • Application Errors

Related Topic

Set Error Handling Properties


System Errors

There are three severity levels for system errors that can occur while the XLANG Scheduler Engine is running. In ascending order of severity, the three levels are:

  • Errors that can be trapped within an XLANG schedule.

  • Errors that will cause an XLANG schedule instance to terminate.

  • Errors that can cause the XLANG Scheduler Engine to fail.

The following topics are covered in this section:

  • Errors That Can Be Trapped Within an XLANG Schedule

  • Errors That Will Cause an XLANG Schedule Instance to Terminate

  • Errors That Can Cause the XLANG Scheduler Engine to Fail


Errors That Can Be Trapped Within an XLANG Schedule

The XLANG Scheduler Engine can trap the following system errors:

  • COM errors that cause failure HRESULTs, for example, an Access Denied message from COM that results in a method being called within an XLANG schedule when permission is inadequate. This can apply to COM or Script bindings.

  • Transaction aborts that are caused by enlisted services, such as the Distributed Transaction Coordinator (DTC) aborting a transaction because the connection to a database was lost. Another example might be the Message Queuing Service aborting a transaction because the Message Queuing Service is unable to queue a message.

To handle a failure HRESULT using logical branching, the _out message coming from a method call must be tested within a decision rule. The HRESULT value will be stored within the __Status__ field of the _out message.

To handle a failure HRESULT using transaction failure processes, the Abort transaction if HRESULT indicates failure property must be set on the last page of the COM Component Binding Wizard or the Script Component Binding Wizard. This property cannot be set unless the action is within a transaction.

Important

  • This option determines whether transactions in which the component is used should be aborted when method calls to the component return a failure HRESULT. This option can be set only if the communication action that uses this port is within the process flow of a transaction

Handling a failure in the Message Queuing or BizTalk Messaging implementation technologies can be performed only with transaction failure processes. To do so, the Use transactional message queues property on the last page of the Message Queuing Binding Wizard must be set (this is done automatically for BizTalk Messaging).

Note

  • A Message Queuing send action that returns successfully indicates that the message has been successfully placed onto the queue. It does not indicate that the message has been delivered.

Related Topics

Application Errors

Errors That Can Cause the XLANG Scheduler Engine to Fail

Errors That Will Cause an XLANG Schedule Instance to Terminate

Handling Exceptions

System Errors


Errors That Will Cause an XLANG Schedule Instance to Terminate

System errors that cause an XLANG schedule instance to fail, but that cannot be trapped within an XLANG schedule,include:

  • A scheduled queue that does not exist.

  • A scheduled channel that does not exist.

  • Data flow from a message that has not arrived yet.

Related Topics

Application Errors

Errors That Can Be Trapped Within an XLANG Schedule

Errors That Can Cause the XLANG Scheduler Engine to Fail

Handling Exceptions

System Errors


Errors That Can Cause the XLANG Scheduler Engine to Fail

System errors that cannot be trapped by the XLANG Scheduler Engine can cause the XLANG Scheduler Engine to fail along with all XLANG schedule instances that are running in the same COM+ application. Among these system errors are certain access violations by components that are running within the XLANG Scheduler Engine's process space. The XLANG Scheduler Engine will attempt to trap these errors, but in many cases the XLANG Scheduler Engine will not be able to trap them. If you have a component that is susceptible to such errors, you might want to put it in a separate COM+ application to circumvent this situation.

Related Topics

Application Errors

Errors That Can Be Trapped Within an XLANG Schedule

Errors That Will Cause an XLANG Schedule Instance to Terminate

Handling Exceptions

System Errors


Application Errors

There are three ways to handle errors that can cause XLANG schedule errors:

  • Use logical branching.

  • Use transactional abort processes.

  • Use timeouts.


Logical Branching

Decisions and rules can be used to branch a process flow on any process page (the Business Process page, any On Failure of Transaction page, or any Compensation for Transaction page). The following illustration shows a simple test of method execution.

In this example, the Clear_out message has a system field named __Status__. In the rule HRESULT Success, the script expression would be Clear_out.[__Status__] >= 0, where a negative HRESULT indicates failure, and 0 or a positive HRESULT indicates success. By using decisions and rules in this way, any data field within any message can be tested (within the VBScript expression of any rule) for exceptions, not exclusively for HRESULTs.

Related Topics

Handling Exceptions

Timeouts

Transactional Abort Processes


Transactional Abort Processes

In BizTalk Orchestration Designer, you can use transactions to group a collection of actions that are performed as a single logical unit of work and ensure that all the actions within the group complete, or none of them complete. By grouping business processes within transactions, BizTalk Orchestration Designer can provide the highest level of structure and reliability.

Process flow within a transaction executes normally, until either the transaction completes or an abort event occurs. An abort event can come from one of several places:

  • Encountering the Abort shape within the process flow.

  • An HRESULT failure that is specified to cause an abort in a port binding.

  • Any binding technology can, at a system level, introduce a failure event that aborts the transaction. For example, Message Queuing might fail to put a message on a queue.

  • The XLANG Scheduler Engine might encounter an error that causes it to abort a transaction within a given instance. For example, there might be a DTC error.

  • Pausing a schedule might require all transactions within that schedule to abort.

  • A time-out within the transaction properties.

When an abort occurs, a transaction might retry from the beginning, depending on the value set in the Retry Count property of the transaction group. If, after a transaction has retried the specified number of times, it continues to fail, the On Failure of Transaction business process will be called. This On Failure of Transaction code provides a structured place to handle the failure of a transaction.

The On Failure of Transaction code does not have to undo any work within the transaction. If the ports are bound to transactional resources, the Distributed Transaction Coordinator will handle the rollback of all enlisted actions within the transaction. Nontransactional resources will not be rolled back. If the transaction is nested within an outer transaction, and if this nested transaction has already committed, the business process sequence will flow to the Compensation for Transaction business process for the nested transaction. The Compensation for Transaction business process is described on the Compensation for Transaction page. This alternate business process must contain actions that can be performed to undo the work within the nested transaction.

When the Compensation for Transaction or the On Failure of Transaction code has completed, the business process sequence will flow out of the bottom of the Transaction shape on the Business Process page. Actions within the business process sequence that occur after a transaction do not receive an explicit indication of whether the transaction completed or aborted. To enable an explicit indication, you can set a flag within a message field on either the On Failure of Transaction page or the Compensation for Transaction page.

Related Topics

Handling Exceptions

Logical Branching

Timeouts


Timeouts

If an action within a transaction does not receive an expected message from a trading partner, the failure is handled as an application error. To test for this error, use timed transactions.

For example, in a simple wire transfer scenario, a timed transaction might contain the following actions within a nested transaction:

  • Withdraw money from a bank account.

  • Initiate the wire transfer process.

The following illustration shows Send money, a nested transaction within a timed transaction called Wire transfer. The nested transaction contains the two actions in the simple wire transfer scenario. When the Initiate the wire transfer action has completed, the business process sequence flows out of the nested transaction. When this happens, the nested transaction is committed; the money has been withdrawn from a bank account and sent to a destination. At this point, the business process sequence flows to the Wait for acknowledgement action in the outer transaction.

In this scenario, the Wire transfer transaction has been configured as a timed transaction. If the sender has not received an acknowledgement of receipt of the money within the specified amount of time, the outer transaction will abort. When this happens, the business process sequence flows to the Compensation for Send money page for the nested transaction. Because the nested transaction has already committed, the alternate business process must describe actions that can be performed to credit the sender's account. When the business process described in the Compensation for Send money page has been performed, the business process sequence flows to the On Failure of Wire transfer page for the outer transaction. This page must contain a business process that describes exception handling for the outer transaction. In this case, the business process might be to send follow-up e-mail to inform the participants of the status of the transfer.

Related Topics

Handling Exceptions

Logical Branching

Transactional Abort Processes


Implementing Business Processes

The Implementation stencil contains four shapes that correspond to the technologies that can be used to implement a port in a business process. Because every action either sends a message to a port or receives a message from a port, the semantic meaning of sending or receiving messages varies, depending on the specific implementation technology.

Using Implementation shapes involves two distinct processes. In the first process, a port is bound to an implementation technology. Conceptually, a port is an abstract location to which a message is sent or from which a message is received. Binding the port to an implementation defines the type of location to which the port is bound. In the second process, an action is connected to the port. This process defines the schema of the message that is sent to or received from the port.

BizTalk Orchestration Designer supports four implementation technologies:

  • COM Components. This technology enables synchronous communication.

  • Windows Script Components. This technology enables synchronous communication.

  • Message Queuing Services. This technology enables asynchronous communication.

  • BizTalk Messaging Services. This technology enables asynchronous communication.

The Separator bar divides the design page of BizTalk Orchestration Designer into a business-process design area on the left side and an implementation area on the right side. To open a port binding wizard, drag one of the Implementation shapes onto the design page, to the right of the Separator bar. You can perform this task on the Business Process page, on the On Failure of Transaction page, and on the Compensation for Transaction page.

Note

  • You cannot configure an envelope in BizTalk Orchestration Designer. Therefore, if you want to submit a flat file to BizTalk Orchestration, use BizTalk Editor to translate the contents of the flat file to XML. You can then submit the XML file to BizTalk Orchestration.

The following topics are covered in this section:

  • Understanding Port Implementations

  • Synchronous and Asynchronous Communication


Understanding Port Implementations

A port is a named location that uses a specific implementation. In an XLANG schedule, ports facilitate synchronous and asynchronous communications and are used to pass messages into or out of the schedule.

In BizTalk Orchestration Designer, a port is defined by the location to which messages are sent or from which messages are received, and the technology that is used to implement the communication action. Ports are bound on the left side to actions in the business process flow of the XLANG schedule; and they are bound on the right side to an implementation technology that can be used to facilitate the required action. The location is uniquely identified by the name of the port.

The location of a port depends in part on the technology used to implement the port. The following table shows the available port implementations and the location that is associated with each port implementation.

Port implementation | Port location
COM Component | A pointer to an activated instance of an object.
Windows Script Component | A pointer to an activated instance of an object.
Message Queuing | A queue path name to a message queue.
BizTalk Messaging | A channel name for a specific BizTalk Messaging channel.

Ports can be described in two ways:

  • Static ports. A static port requires all information about the port location and implementation be provided for an XLANG schedule at design time. The designer who creates the XLANG schedule must know the location to which messages are sent or from which messages are received, as well as the technology chosen to implement the communication action.

  • Dynamic ports. A dynamic port requires that specific location information be provided for an XLANG schedule at run time. The implementation for a dynamic port is chosen at design time, but the location of this port is not known until the XLANG schedule is running. The location for a dynamic port is provided by a message that passes the location information to the reference for the port. This message must arrive at a point in the process flow of the XLANG schedule before the communication that uses this port implementation can be used.

    If you want to use a dynamic port for a communication, and the XLANG schedule has not received a message that contains the reference to the port before the schedule tries to complete the action, an error is generated.

Both static and dynamic ports provide options for synchronous and asynchronous communications, but the port implementations for these communications differ depending on the technology that you use to implement the port.

Any port can be either a static port or a dynamic port; however, all ports cannot implement synchronous and asynchronous communications. If you want to create a synchronous communication action, you must use a COM or script component port implementation. If you want to create an asynchronous communication action, you must use a Message Queuing or BizTalk Messaging port implementation.

The following topics are covered in this section:

  • Static and Dynamic Ports

  • Using the COM Component Shape

  • Using the Script Component Shape

  • Using the Message Queuing Shape

  • Using the BizTalk Messaging Shape

Note

  • When non-XML text documents are received by an XLANG schedule from a port that is implemented by Message Queuing or BizTalk Messaging, carriage-return (CR) characters are removed from the document. If a MIME-encoded message is sent to a schedule that must later send or use the data elsewhere, the document sent out by the schedule does not contain the CR characters and does not appear to be a valid MIME-encoded document. If this is an issue for you, you should write a custom component to be called from the schedule to restore the CR characters to the document.

Related Topic

Synchronous and Asynchronous Communication


Static and Dynamic Ports

Static and dynamic port behavior varies depending on the type of implementation you use.

Port implementations that use COM or Script components

For a port implementation that uses COM or script components, the static and dynamic properties represent how a component is instantiated:

  • Static. For an XLANG schedule that uses a static port, the XLANG Scheduler Engine instantiates the component that is defined for this port implementation.

  • Dynamic. For an XLANG schedule that uses a dynamic port, the XLANG Scheduler Engine does not instantiate the component. Instead, the XLANG schedule waits for another application to instantiate the component. The object instance must be sent back to the XLANG schedule as a field in a message. On the Data page, a connection must be drawn between that message field and the port reference for the port that uses this implementation. The XLANG schedule intercepts both the method request and the method response from the component.

In addition to the Static and Dynamic options, there is a third choice:

  • No instantiation. For an XLANG schedule that uses a port with no instantiation, the component is not instantiated, and no code for the method call is executed. Instead, when the XLANG schedule intercepts the method request information, it returns this information as the response. The method call is circumvented.

Port implementations that use Message Queuing

In a port implementation that uses Message Queuing, the static and dynamic properties are represented as static and dynamic queues:

  • Static queue. A static port uses a static queue that is a known, preexisting queue. You can assign this queue at design time.

    If you use a static queue, you can choose to either use a known queue that never changes, or you can create a new instance of the same queue each time the XLANG schedule is run. The per-instance queue is identified by a unique ID that is appended to the name of the queue.

  • Dynamic queue. A dynamic port uses a dynamic queue that is unknown at design time. The information for a dynamic queue must be provided at run time within a message field. On the Data page you must create a link from a message field to the port reference for this port. When a message arrives that contains the queue name, the XLANG schedule can use the assigned queue. The message that contains the queue name must arrive before the communication that uses this port implementation can be used.

Port implementations that use BizTalk Messaging

In a port implementation that uses BizTalk Messaging, the static and dynamic properties are represented as static and dynamic channels. Dynamic channels can be used only when you are sending messages. Dynamic channels cannot be used to receive messages.

  • Static channel. A static port uses a static channel that is a known, pre-existing channel. You can assign this channel at design time, and it never changes.

  • Dynamic channel. A dynamic port sends a document to a destination that is unknown at design time. This destination value must be provided at run time within a message field. On the Data page you must create a link from a message field to the port reference for this port. When the message arrives that contains the destination value, the XLANG schedule will send the document to a messaging channel that is associated with an open destination port. This port will then send the message to the destination value specified at run time. Note that the messaging channel must be set to Home Organization and specify the same document definition as the message to be sent out. The message that contains the destination value must arrive before the communication that uses this port implementation can be used.

A port that uses a dynamic channel enables an XLANG schedule to determine where to send a message at run time, rather than requiring that a pre-determined destination be defined at design time. This property defines which channel is used when the XLANG schedule passes the message to BizTalk Messaging Services.

The dynamic channel should not be confused with an open channel that is configured in BizTalk Messaging Manager. An open channel enables the source organization to be determined at run time from information within the document or in the parameters submitted with the document. This property defines the source of the documents. For more information about open channels, see Understanding Channels.

The message that is passed to a port that uses a dynamic channel could specify either an open channel or a channel that is not open when passing the channel information to BizTalk Messaging Services.

Note

  • It is recommended that if you are using a dynamic channel, you add an action in your schedule to do address validation or custom error handling. This avoids potential data loss that can result from an address in an invalid format, such as a badly formed address or an address in a protocol other than HTTP, HTTPS, or SMTP.

Related Topics

Implement Ports

Synchronous and Asynchronous Communication

Understanding Channels

Using the BizTalk Messaging Shape

Using the COM Component Shape

Using the Message Queuing Shape

Using the Script Component Shape


Using the COM Component Shape

The COM Component shape enables you to use preexisting components or applications to perform actions within an XLANG schedule. Because COM technology is synchronous, there is always a bidirectional flow of messages when an action is performed. In contrast, the flow of messages for an asynchronous technology is in one direction.

The XLANG Scheduler Engine supports sending or receiving messages by the use of Action shapes. When you bind a port to a COM component in BizTalk Orchestration Designer, the port is bound to an interface that is implemented by a COM component that has been registered on your system.

A send action that is connected to the port represents the invocation of a specific method call by the XLANG Scheduler Engine. The IN and IN/OUT parameters are sent to the port. In return, a message with a schema that is defined by the IN/OUT and OUT parameters of the method call is received from the port. The method call is supported by the interface that is bound to the port.

A receive action that is connected to the port waits for an external application to make a method call to the port. The IN and IN/OUT parameters define the schema of the message that is received by the port, and the IN/OUT and OUT parameters define the schema of the message that is sent from the port.

For every action that is connected to a port and bound to a COM component, two messages are exchanged. The messages identify the method on the interface that is invoked. The schema for the messages correspond to the IN and IN/OUT parameters (and to the IN/OUT and OUT parameters) of the method signature. Because the type library for the components is accessible, BizTalk Orchestration Designer can automatically build the schema for these messages without querying the user for this information.

Important

  • Use COM components carefully when you implement a long-running business process. If components that hold state are used in an XLANG schedule, it is recommended that you use components that can be saved by using either the IPersistStream or IPersistStreamInit interface. This ensures that the XLANG schedule can store its state along with the state of the components. XLANG schedules must be able to hold state and run durably over a long period of time. If components that do not hold state are used, a new instance of the component is created every time the XLANG schedule is rehydrated. However, the use of components that do not hold state should not affect the outcome of the schedule.

Binding is the process of specifying the technology that will implement a port. The COM Component Binding Wizard is made up of the following pages:

Welcome to the COM Component Binding Wizard

On the Welcome to the COM Component Binding Wizard page, you can create and name a port for which you want to define an implementation.

Static or Dynamic Communication

On the Static or Dynamic Communication page, you can define how the component will be instantiated. The following table lists and describes the static and dynamic communication settings.

Static or dynamic communication | Description
Static | Select this option if you can provide the XLANG Scheduler Engine with all the required information to complete the implementation at design time.
Dynamic | Select this option if the XLANG Scheduler Engine requires additional information at run time to complete the implementation.
No instantiation | Select this option to enable the XLANG schedule to receive data by using a method call without activating the component. When you select No instantiation, method calls to this component are intercepted, the XLANG Scheduler Engine stores the arguments, and the call returns to the caller. The component is never instantiated.

Class Information

On the Class Information page, you can select a class from a list of registered components or from a moniker.

Interface Information

On the Interface Information page, you can select the interface that you want to use. This page is displayed only if the selected class contains more than one interface. Visual Basic components always have a single interface.

Method Information

On the Method Information page, you can select the methods that you want to use. This page is displayed only if the selected class contains more than one method.

Advanced Port Properties

On the Advanced Port Properties page, you can configure security, transaction support, state management support, and error handling.

The state management support properties of the COM Component shape include:

  • Persisting the state of an XLANG schedule before the start of a transaction, and after the completion of a transaction. This provides durability, ensuring that all committed data modifications are permanently in place in the system. This also enables retries of a transaction if a failure occurs.

  • Optimizing instance management by enabling the XLANG Scheduler Engine to dehydrate the XLANG schedule and then rehydrate the schedule when the message it is waiting for arrives.

You can use the COM Component shape to request authenticated user information for the messages that are received.

Security area

The following table lists and describes the sender identity confirmation settings.

Sender identity confirmation | Description
Not required | Select this option if you want the XLANG schedule to be able to receive a message without knowing the identity of the sender.
Optional | Select this option if you want the XLANG Scheduler Engine to identify the sender when the component receives a message, if the information is available.
Required | Select this option if you do not want the XLANG Scheduler Engine to receive a message unless it can identify the sender.

Transaction support area

The following table lists and describes the transaction support settings.

Transaction support | Description
Disabled | This is for all non-COM+ components. This option specifies that the component will ignore COM transaction management.
Not Supported | This is only for COM+ components. This option specifies that the component will not participate in a transaction, or propagate the transactions of other components.
Supported | This is only for COM+ components. This option specifies that if a transaction is associated with the port to which the component is bound, the component will be included in the transaction. Otherwise, the component will not have a transaction.
Required | This is only for COM+ components. This option specifies that if a transaction is associated with the port to which the component is bound, the component will be included in the transaction. If there is no transaction associated with the port to which the component is bound, a new transaction will be created for the component.
Requires New | This is only for COM+ components. This specifies that a new transaction will always be created for the component.

State management support area

The following table lists and describes the state management support settings.

State management support | Description
Holds no state | This specifies that the XLANG Scheduler Engine will terminate the component instance when it is dehydrated. If you select this setting, the XLANG Scheduler Engine will create a new component instance, if it is required, when the schedule is rehydrated.
Holds state, but doesn't support persistence | This specifies that the XLANG Scheduler Engine will be required to leave the component instance running. If the system fails while the application is dehydrated, any state that has been held in this component will be lost.
Holds state, and does support persistence | This specifies that the XLANG Scheduler Engine will remove the component instance from memory, and then restore it to memory by calling either IPersistStream or IPersistStreamInit on the component during dehydration, and then again during rehydration.

Error handling area

In the Error handling area, select the Abort transaction if the method returns a failure HRESULT check box if you want the XLANG Scheduler Engine to abort the transaction when an error is returned from a method in a component.

Notes

  • When an action communicates with a port bound to a COM component and the specified method does not exist on the component, the XLANG schedule instance will failfast with an event log entry.

  • BizTalk Orchestration Designer does not support binding to a COM component method that contains a parameter derived from IDispatch. However, BizTalk Orchestration Designer does support binding to COM component methods containing parameters of type IDispatch.

  • You should not use the names of system fields as parameter names in COM components because of the potential for name collisions. For more information, see System Fields.

  • If an application has a reference to a COM component in an XLANG schedule by means of the IUnknown interface, that reference will become invalid after the XLANG schedule instance is dehydrated and rehydrated. All persistable COM components will be properly rehydrated to the state they were in at the time of dehydration, but the interfaces will be assigned new addresses. This is expected and normal behavior. If two or more message fields in any single XLANG schedule instance contain pointers to the same COM component, and the schedule is dehydrated, these message fields will contain pointers to a single COM component after rehydration. However, the COM component will not be the same one that existed before dehydration. It will be a newly created COM component that is similar to the COM component that existed before dehydration. If the original COM component is persistable, the new COM component will have the same state that the original COM component had before dehydration.

  • Component uniqueness is not maintained across while loops. If one message within a while loop contains a field that has a pointer to a COM component, and a different message outside the while loop contains a field that has a pointer to the same COM component, after dehydration and rehydration these two message fields will no longer have pointers to a single COM component. The two message fields will have pointers to two separate COM components that are similar to the original COM component. If the original COM component is persistable, the two new COM components will hold the same state that the original COM component had before dehydration.

  • If you want to bind the port to a Microsoft Visual Basic component, you must do so when Visual Basic is not in debug mode; otherwise the component will not be listed in the COM Component Binding Wizard.

Related Topics

Static and Dynamic Ports

Synchronous and Asynchronous Communication

Using the BizTalk Messaging Shape

Using the Message Queuing Shape

Using the Method Communication Wizard

Using the Script Component Shape


Using the Script Component Shape

The Script Component shape enables you to use a preexisting Windows Script Component to perform actions within an XLANG schedule. Because the Script Component is synchronous, there is always a bidirectional flow of messages when an action is performed. In contrast, the flow of messages for an asynchronous technology is in one direction.

A send action that is connected to the port represents the invocation of a specific method call by the XLANG Scheduler Engine. The IN and IN/OUT parameters are sent to the port. In return, a message with a schema that is defined by the IN/OUT and OUT parameters of the method call is received from the port. The method call is supported by the interface that is bound to the port.

A receive action that is connected to the port waits for an external application to make a method call to the port. The IN and IN/OUT parameters define the schema of the message that is received by the port, and the IN/OUT and OUT parameters define the schema of the message that is sent from the port.

For every action that is connected to a port and bound to a Script component, two messages are exchanged. The messages identify the method on the interface that is invoked. The schema for the messages corresponds to the IN and IN/OUT parameters (and to the IN/OUT and OUT parameters) of the method signature. Because the type library for the components is accessible, BizTalk Orchestration Designer can automatically build the schema for these messages without querying the user for this information.

The XLANG Scheduler Engine waits until the method returns before continuing the business process. To send a message, the XLANG Scheduler Engine invokes the specified method of a Windows Script Component.

To create a new script component binding, drag the Script Component shape from the Implementation stencil onto the BizTalk Orchestration design page, to the right of the Separator bar. To edit an existing script component, right-click the Script Component shape and click Edit Properties. Both actions start the Script Component Binding Wizard. Binding is the process of specifying the technology that will implement a port. The Script Component Binding Wizard is made up of the following pages:

Welcome to the Script Component Binding Wizard

On the Welcome to the Script Component Binding Wizard page, you can create and name a port for which you want to define an implementation.

Static or Dynamic Communication

On the Static or Dynamic Communication page, you can define how the component will be instantiated. The following table lists and describes the static and dynamic communication settings.

Static or dynamic communication | Description
Static | Select this option if you can provide the XLANG Scheduler Engine with all the required information to complete the implementation at design time.
Dynamic | Select this option if the XLANG Scheduler Engine requires additional information at run time to complete the implementation.
No instantiation | Select this option to enable the XLANG schedule to receive data by using a method call without activating the component. When you choose No instantiation, method calls to this component are intercepted, the XLANG Scheduler Engine stores the arguments, and the call returns to the caller. The component is never instantiated.

Specify the Script File

On the Specify the Script File page, you can type the path to the Windows Script Component (.wsc) file that you want to use.

Component Instantiation Information

On the Component Instantiation Information page, you can specify if the XLANG Scheduler Engine will use a moniker or a Prog ID to instantiate the script component.

Method Information

On the Method Information page, you can select the methods that belong to the selected class.

Advanced Port Properties

On the Advanced Port Properties page, you can configure security, transaction support, and error handling. You can use the Script Component shape to request authenticated user information for the messages that are received.

Security area

The following table lists and describes the sender identity confirmation settings.

Sender identity confirmation | Description
Not required | Select this option if you want the XLANG schedule to be able to receive a message without knowing the identity of the sender.
Optional | Select this option if you want the XLANG Scheduler Engine to identify the sender when the component receives a message, if the information is available.
Required | Select this option if you do not want the XLANG Scheduler Engine to receive a message unless it can identify the sender.

Transaction support area

The following table lists and describes the transaction support settings.

Transaction support | Description
Disabled | This is for all non-COM+ components. This option specifies that the component will ignore COM transaction management.
Not Supported | This is available only if the script is installed as a COM+ component. This specifies that the component will not participate in a transaction, or propagate the transactions of other components.
Supported | This is available only if the script is installed as a COM+ component. This specifies that if a transaction is associated with the port to which the component is bound, the component will be included in the transaction. Otherwise, the component will not have a transaction.
Required | This is available only if the script is installed as a COM+ component. This specifies that if a transaction is associated with the port to which the component is bound, the component will be included in the transaction. If there is no transaction associated with the port to which the component is bound, a new transaction will be created for the component.
Requires New | This is available only if the script is installed as a COM+ component. This specifies that a new transaction will always be created for the component.

Error handling area

In the Error handling area, select the Abort transaction if the method returns a failure HRESULT check box if you want the XLANG Scheduler Engine to start an abort process when an error is returned from a method in a component. To use On Failure of Transaction and Compensation for Transaction pages, this option must be selected for the XLANG Scheduler Engine. If this option is not selected, error-recovery processes that are defined on either page will not be run.

Important

  • When you use Windows Script Components, they must adhere to the following rules:
    • Argument declarations must be by reference, not by value.

    • Visual Basic Scripting subroutines are not supported. Only functions are supported.

    • Multiple components cannot be used within a single .wsc file.

Notes

  • When an action communicates with a port bound to a script component and the specified method does not exist within the script component, the XLANG schedule instance will failfast with an event log entry.

  • Script components that have been run by the XLANG Scheduler Engine cannot be modified until both the XLANG Scheduler Engine and the Windows Script Host have been shut down.

Related Topics

Static and Dynamic Ports

Synchronous and Asynchronous Communication

Using the BizTalk Messaging Shape

Using the COM Component Shape

Using the Message Queuing Shape

Using the Method Communication Wizard


Using the Message Queuing Shape

The Message Queuing shape enables an XLANG schedule to communicate with another XLANG schedule (or with an application), in a loosely coupled manner, using a queue. To enable communication between XLANG schedules and applications, messages are dropped onto a queue and then read. A single XLANG schedule might use several ports that are bound to the Message Queuing shape.

When a port is bound to the Message Queuing shape, it is also bound to a message queue. The port can be bound to a named queue or to a per-instance queue. If a port is bound to a per-instance queue, a unique queue is created and used for each instance of this XLANG schedule. Per-instance queues provide a convenient way for an XLANG schedule to have a separate queue for each XLANG schedule instance.

When an action is connected to a port that is bound to a message queue, the message that is sent or received by the action must be defined. Because multiple message types can be stored in a queue, the message type helps identify the type of message that should be received by the action. During a Send action, the message type is marked on the label property of the message when it is written to the queue.

The Message Queuing shape represents the Message Queuing Service that is used to send or receive messages. To receive a message, the XLANG Scheduler Engine requires the name of the queue that is used and the name of the root element of the XML schema that is contained within that message. To send a message, the XLANG Scheduler Engine needs the name of the queue that is used to transmit messages.

If you configure an XLANG schedule instance to use Message Queuing to receive messages, you can use the XML Communication Wizard to specify the destination format as either XML or string.

To create a new Message Queuing binding, drag the Message Queuing shape from the Implementation stencil onto the BizTalk Orchestration design page, to the right of the Separator bar. To edit an existing Message Queuing implementation, right-click the Message Queuing shape and click Edit Properties. Both actions start the Message Queuing Binding Wizard. Binding is the process of specifying the technology that will implement a port. The Message Queuing Binding Wizard is made up of the following pages:

Welcome to the Message Queuing Binding Wizard

On the Welcome to the Message Queuing Binding Wizard page, you can create and name a port for which you want to define an implementation, or you can choose an existing, unbound port.

Static or Dynamic Queue Information

On the Static or Dynamic Queue Information page, you can specify if the message queue will be defined at design time or at run time. Choose one of the following options:

  • 0Choose Static queue if you can provide queue information at design time.

  • Choose Dynamic queue if you want the XLANG Scheduler Engine to acquire information from an external source at run time to determine the queue name.

Queue Information

On the Queue Information page, you can create a new queue or specify an existing queue. Choose one of the following options:

  • Choose Create a new queue for every instance if you want the XLANG Scheduler Engine to create a per-instance queue for every XLANG schedule instance.

  • Choose Use a known queue for all instances if you want the XLANG Scheduler Engine to use a known queue.

Advanced Port Properties

On the Advanced Port Properties page, you can configure security and choose whether or not you want to enable transaction support. You can use the Message Queuing shape to request authenticated user information for the messages that are received.

Security area

The following table lists and describes the sender identity confirmation settings.

Sender identity confirmation | Description
Not required | Select this option if you want the XLANG schedule to be able to receive a message without knowing the identity of the sender.
Optional | Select this option if you want the XLANG Scheduler Engine to identify the sender when the component receives a message, if the information is available.
Required | Select this option if you do not want the XLANG Scheduler Engine to receive a message unless it can identify the sender.

You can also select or clear the Use a Windows Group or User Name to control the queue check box. If you select the check box, enter the name of the user or group that is permitted to write messages to the queue. This option is available only if you are using a static queue.

Transaction support area

In the Transaction support area, select the Transactions are required with this queue check box to enable transaction support.

Notes

  • Currently, the supported name format for queues does not enable remote access to a queue on another computer. Use public queues instead of private queues when an XLANG schedule communicates with an application on a remote computer.

  • When an action communicates with a port bound to Message Queuing and the specified queue for the binding does not exist, the XLANG schedule instance will failfast with an event log entry.

  • It is important that the XLANG Scheduler Engine be able to determine if a queue is transactional or not. If a queue is in a transactional context and a message is sent to the queue, the XLANG Scheduler Engine must know whether the transaction should be used to communicate with the queue. If the port binding is configured with the Transactions are required with this queue check box selected, the XLANG Scheduler Engine will failfast the XLANG schedule if it is determined at run time that the queue is not transactional.

Related Topics

Static and Dynamic Ports

Synchronous and Asynchronous Communication

Using the BizTalk Messaging Shape

Using the COM Component Shape

Using the Script Component Shape

Using the XML Communication Wizard


Using the BizTalk Messaging Shape

The BizTalk Messaging shape represents BizTalk Messaging Services that are used to exchange messages between BizTalk Orchestration Services and BizTalk Messaging Services. To receive a message, the XLANG Scheduler Engine requires the HTTP URL address used by the BizTalk Messaging Service to receive documents, the name of the channel, and the message type of the outbound document definition. Receiving documents for XLANG schedule activation only requires the message type of the document definition. To send a message, the XLANG Scheduler Engine requires the name of the channel and the message type of the inbound document definition. For more information about exchanging messages between BizTalk Orchestration Services and BizTalk Messaging Services, see Integrating BizTalk Services.

Important

  • If you configure a port to activate a new XLANG schedule when a message arrives, you must observe the following restrictions:
    • Only one port in a schedule can be used to activate the XLANG schedule when the message arrives.

    • Only one action can receive through this port.

    • This one action cannot be in a loop body.

    • You cannot draw a data flow connection from the port reference for this port to any other message in the schedule.

To create a new BizTalk Messaging binding, drag the BizTalk Messaging shape from the Implementation stencil onto the BizTalk Orchestration design page, to the right of the Separator bar. To edit an existing BizTalk Messaging implementation, right-click the BizTalk Messaging shape and click Edit Properties. Both actions start the BizTalk Messaging Binding Wizard. Binding is the process of specifying the technology that will implement a port. The BizTalk Messaging Binding Wizard is made up of the following pages:

Welcome to the BizTalk Messaging Binding Wizard

On the Welcome to the BizTalk Messaging Binding Wizard page, you can create and name a port for which you want to define an implementation, or you can choose an existing, unbound port.

Communication Direction

On the Communication Direction page, you can specify if you want to configure the port to send or receive messages.

Static or Dynamic Channel Communication

The Static or Dynamic Channel Communication page appears only if you choose Send on the Welcome to the BizTalk Messaging Binding Wizard page. On the Static or Dynamic Channel Communication page, you can specify if you want the XLANG Scheduler Engine to use a static channel that will be defined at design time or a dynamic channel that will be defined at run time.

XLANG Schedule Activation Information

On the XLANG Schedule Activation Information page, you can specify if an XLANG schedule instance will be activated on this receive action. If you choose Yes, the BizTalk Messaging Binding Wizard finishes. If you choose No, the Channel Information page appears.

Channel Information

On the Channel Information page, you can specify the name of the channel and the HTTP URL address used by the BizTalk Messaging Service to receive documents.

Notes

  • When an action communicates with a port bound to BizTalk Messaging and the specified channel for the binding does not exist, the XLANG schedule instance will failfast with an event log entry.

  • Including separate send and receive BizTalk Messaging bindings in a single transaction might result in a deadlock condition that will cause the transaction to fail.

  • Action events related to messages processed by an XLANG schedule that are either sent to or received from BizTalk Messaging Services can be tracked in the Tracking database. For more information, see Tracking XLANG Schedule Events in the Tracking Database.

Related Topics

Static and Dynamic Ports

Synchronous and Asynchronous Communication

Using the COM Component Shape

Using the Message Queuing Shape

Using the Script Component Shape

Using the XML Communication Wizard


Synchronous and Asynchronous Communication

All communication to a COM or script component implementation is synchronous. If you want to create a communication flow to a port that uses a COM component or script component implementation, you must use the Method Communication Wizard.

All communication to an unbound port, or to a Message Queuing or BizTalk Messaging implementation, is asynchronous. If you want to create a communication flow to a port that uses a Message Queuing or BizTalk Messaging implementation, or if you want to create a communication flow to an unbound port, you must use the XML Communication Wizard.

The following illustration and text describes what an XLANG schedule does for the four possible communication actions.

Synchronous and asynchronous communication overview

  1. Synchronous receive action
    1. The XLANG schedule waits for another application to send a method request and instantiate a component.

    2. The schedule intercepts the method request.

    3. The schedule waits for the component to return the method response.

    4. The schedule intercepts the method response.

    5. The schedule continues with the next action in the business process flow.
  2. Synchronous send action
    1. The XLANG schedule initiates the method request and instantiates the component.

    2. The schedule waits for the component to return the method response.

    3. The schedule receives the method response.

    4. The schedule continues with the next action in the business process flow.
  3. Asynchronous receive action
    1. The XLANG schedule waits for another application to send a message to a message queue or to a BizTalk Messaging channel.

    2. The XLANG schedule receives the message from the message queue or from the channel.

    3. The schedule continues with the next action in the business process flow.
  4. Asynchronous send action
    1. The XLANG schedule sends a message to a message queue or to a BizTalk Messaging channel.

    2. The schedule continues with the next action in the business process flow.

    3. Another application receives the message from the message queue or BizTalk Messaging channel.

Notes

  • A special case exists for the synchronous receive action. If you choose No instantiation in the COM Component Binding Wizard or the Script Component Binding Wizard, the component is not instantiated, and no code for the method call is executed. Instead, when the XLANG schedule intercepts the method request information, it returns this information as the response. The method call is circumvented. For more information about static and dynamic ports and the COM Component Binding Wizard and the Script Component Binding Wizard, see the following topics:
    • Static and Dynamic Ports

    • Implement Ports

    • Using the COM Component Shape

    • Using the Script Component Shape
  • Action events related to messages processed by an XLANG schedule that are either sent to or received from BizTalk Messaging Services can be tracked in the Tracking database. For more information, see Tracking XLANG Schedule Events in the Tracking Database.

This section contains information about the following topics:

  • Using the Method Communication Wizard

  • Synchronous Communication

  • Using the XML Communication Wizard

  • Asynchronous Communication

Related Topics

Implement Ports

Static and Dynamic Ports

Using the COM Component Shape

Using the Script Component Shape


Using the Method Communication Wizard

On the Business Process page, the Compensation for Transaction page, and the On Failure of Transaction page, you can use the Method Communication Wizard to define the flow of messages between an Action shape and a COM Component shape or a Script Component shape. If a message is sent, the XLANG schedule will call the method with the _in message and then wait to receive the _out message from the component. If a message is to be received, the XLANG schedule will wait for another application to send the _in message to the method (by calling a method on the port), and then wait for the _out message from the component to be sent back to the other application.

Notes

  • For Visual Basic programmers, ByVal parameters appear only in the _in message. All other parameters appear in both the _in message and the _out message.

  • For C programmers, IN parameters appear in the _in message, OUT parameters appear in the _out message, and IN,OUT parameters appear in both messages.

  • For Visual Basic programmers and C programmers, if a parameter appears in both the _in message and the _out message, the _in message contains the contents of what was sent into the method, and the _out message contains the contents of what was returned by the method.

To start the Method Communication Wizard, drag the right control handle ( Control handle) of an Action shape to the connection point ( Connection point) on a port bound to a COM Component shape or a Script Component shape. The Method Communication Wizard is made up of the following pages:

Welcome to the Method Communication Wizard

On the Welcome to the Method Communication Wizard page, you can specify whether the XLANG Scheduler Engine will call a method or wait for a method call. If you specify that the XLANG Scheduler Engine will wait for a method call, you can set a latency value to indicate an amount of time in seconds that the XLANG Scheduler Engine is likely to have to wait before a message arrives. If this value is 180 seconds or less, the XLANG schedule instance will never be dehydrated to the persistence database. If this value is greater than 180 seconds, the XLANG schedule instance will be dehydrated to the persistence database immediately. By default, the latency value is set to zero, indicating that the message is expected to arrive immediately.

If an XLANG schedule instance is rehydrated for any reason other than the arrival of a message for which an action is waiting (and if the XLANG schedule instance then enters a quiescent state), the specified latency value is used to determine whether the XLANG schedule instance will be immediately dehydrated. For example, this can occur when a concurrent branch receives a message for which it was waiting, or when a computer restart causes all XLANG schedule instances to rehydrate. In this situation, the latency value is evaluated from the point when the XLANG schedule instance enters a quiescent state. If the amount of time from the beginning of the XLANG Scheduler Engine's original waiting period (combined with the latency value) is more than 180 seconds from when the XLANG Scheduler Engine entered the quiescent state after rehydration, the XLANG schedule instance will be dehydrated to the persistence database immediately. This point in the XLANG schedule instance can occur long after the XLANG Scheduler Engine begins monitoring the arrival of a message.

Message Information

On the Message Information page, you can specify whether a new message or a reference to an existing message should be created. If you specify that a reference to an existing message should be created, you can select from a list of previously created messages that have been sent to or received from methods, and that already have corresponding Message shapes. If the message you want to use is not listed, specify that a new message should be created, and define the data flow for the new message.

Message Specification Information

On the Message Specification Information page, you can select a message specification for the message you created or referenced on the Message Information page.

Related Topics

Asynchronous Communication

Dehydration and Rehydration

Persistence

Synchronous and Asynchronous Communication

Synchronous Communication

Using the XML Communication Wizard


Synchronous Communication

The only methods available for use in synchronous communication are those that were selected for the port implementation. Methods from other port implementations cannot be used, and XML messages from asynchronous communication flows cannot be used. To change the available methods, rerun the appropriate binding wizard and select different methods.

The IN and OUT parameters are automatically determined by the parameter requirements of the method that you choose. Both parameter lists contain the name and data type of the parameter. In addition to any parameters associated with the method, a message also contains certain required system fields. A synchronous message always contains the following system fields:

  • __Sender__

    This system field is a required IN parameter for the method used in a synchronous message.

  • __Status__

    This system field is a required OUT parameter for the method used in a synchronous message.

Synchronous Messages

When you create a synchronous communication, a Message is created on the Data page. The Message corresponds to the method and parameters that are used in the communication flow. The Message contains all IN parameters for the method, and all OUT parameters for the method.

It is possible for a method to contain no parameters; however, the Message always contains required system fields. The Message schema is shown in the following example:

Method name_in
__Sender__   string
   parameter 1   Data type 1
   parameter 2   Data type 2
   parameter n   Data type n
Method name_out
__Status__   string
   Parameter 1   Data type 1
   Parameter 2   Data type 2
   Parameter n   Data type n

The following illustration shows a synchronous message pair that contains the system fields __Sender__ and __Status__, as well as IN and OUT parameters for the method call.

A synchronous message pair that contains a method call and its associated values

Related Topics

Dehydration and Rehydration

Persistence

Synchronous and Asynchronous Communication

Using the Method Communication Wizard


Using the XML Communication Wizard

On the Business Process page, the Compensation for Transaction page, and the On Failure of Transaction page, you can use the XML Communication Wizard to define the flow of messages between an Action shape and a Message Queuing shape, a BizTalk Messaging shape, or an unbound port. To start the XML Communication Wizard, drag the right control handle ( Control handle) of an Action shape to the connection point ( Connection point) on an unbound port, or on a port bound to a Message Queuing shape or a BizTalk Messaging shape. The XML Communication Wizard is made up of the following pages:

Welcome to the XML Communication Wizard

On the Welcome to the XML Communication Wizard page, you can specify whether the port will send a message to an action or receive a message from an action. If you are creating the communication between an action and a port that has been implemented using the BizTalk Messaging shape, the communication direction has already been configured. This occurred when the BizTalk Messaging Binding Wizard was used to create the port binding.

If the port is configured to receive messages, you can set a latency value to indicate an amount of time in seconds that the XLANG Scheduler Engine will wait before a message arrives. If this value is 180 seconds or less, the XLANG schedule instance will never be dehydrated to the persistence database. If this value is greater than 180 seconds, the XLANG schedule instance will be dehydrated to the persistence database immediately. By default, latency is set to zero seconds, indicating that the message is expected to arrive immediately.

If an XLANG schedule instance is rehydrated for any reason other than the arrival of a message for which an action is waiting (and if the XLANG schedule instance then enters a quiescent state), the specified latency value is used to determine whether the XLANG schedule instance will be immediately dehydrated. For example, this can occur when a concurrent branch receives a message for which it was waiting, or when a computer restart causes all XLANG schedule instances to rehydrate. In this situation, the latency value is evaluated from the point when the XLANG schedule instance enters a quiescent state. If the amount of time from the beginning of the XLANG Scheduler Engine's original waiting period (combined with the latency value) is more than 180 seconds from when the XLANG Scheduler Engine entered the quiescent state after rehydration, the XLANG schedule instance will be dehydrated to the persistence database immediately. This point in the XLANG schedule instance can occur long after the XLANG Scheduler Engine begins monitoring the arrival of a message.

Message Information

On the Message Information page, you can specify whether a new message or a reference to an existing message should be created. If you specify that a new message should be created, define the data flow for the new message. For more information about data flow, see Data Handling. The Label property of a message can be used to optimize the performance of a schedule in the following manner:

  • If the Label property of the message is identical to the XML root element that is specified when creating a new Message shape, the XLANG Scheduler Engine retrieves the message.

  • If the Label property does not match the value provided for the XML root element, the XLANG Scheduler Engine examines the contents of the message. If the value of the XML root element that is specified when a new Message shape is created matches the actual XML root element, the XLANG Scheduler Engine retrieves the message. Otherwise, the XLANG Scheduler Engine leaves the message on the queue and checks the next message.

XML Translation Information

On the XML Translation Information page, you can specify whether you want messages sent to or received from the queue as XML formatted data or as text strings. If you specify that you want messages sent as text strings, the XLANG Scheduler Engine's standard XML wrapper will be removed from the messages.

Message Type Information

On the Message Type Information page, you can specify a label that the XLANG Scheduler Engine should use to identify messages of the type you define. The text that you enter is used to identify the correct messages to receive from the message queue. If you select the same message type for two different messages, make sure the field names, field types, and XPath queries match exactly. The XLANG Scheduler Engine will report an error if there is an inconsistency between messages of the same message type on the same port. On the Message Type Information page, in the Message type box, type a label designation for the message. The XLANG Scheduler Engine will perform the following procedures, based on the information you provide:

  • The XLANG Scheduler Engine will attempt to match the message type information with the message label in the queue. When the message type is not matched, the message will be ignored, and the XLANG Scheduler Engine continues looking for new incoming messages that might match. This enables multiple actions to receive multiple message types from a single message queue.

  • When you use the BizTalk Messaging shape for activation, the XLANG Scheduler Engine will use the name of the activation channel's outbound document definition as the message label when it delivers the message to the queue. The action that will use this message should likewise use the name of the activation channel's outbound document definition for its message type.

  • If the message is in XML format on the queue, the XLANG Scheduler Engine will attempt to match the message type information with the XML root element of the message on the queue.

You can also use the instance ID — the globally unique identifier (GUID) of the schedule instance — as the label for the message by checking Use Instance Id as Message Label. This provides a useful mechanism for correlation if you want to use a single queue to handle messages for all instances of a schedule. For more on this subject, see the discussion of correlating the exchange of messages to XLANG schedule instances in Instance Management.

Message Specification Information

On the Message Specification Information page, you can type the path to the message specification (.xml) file that you want to use, or you can browse to it. If the message specification you select is a specification that was created using BizTalk Editor, you will be able to add fields to the data scope of the XLANG Scheduler Engine. You can validate messages against the specification by selecting the Validate messages against the specification check box. By clicking Browse on the Message Specification Information page, you can display the Browse for Specification dialog box. You can use the Browse for Specification dialog box to find the specification that you want to use.

If you have not selected a specification, you can click Create on the Message Specification Information page to open BizTalk Editor. If you have already selected a specification, you can click Edit on the Message Specification Information page to open BizTalk Editor with the selected specification.

By clicking Add on the Message Specification Information page, you can display the Field Selection dialog box. In the Field Selection dialog box, in the Select node tree, you can expand any nodes that you want, and then click the field that you want to add. In the Field Selection dialog box, you can edit the name and the node path for fields you want to add to the message shape for the selected port. The data type fields are displayed, but they cannot be edited.

Notes

  • Validation is available only when a message is received. If a message is sent, the validation check box is ignored.

  • XML data types such as enumeration and number that do not have corresponding OLE Automation types are converted to type string in BizTalk Orchestration Designer and XLANG. A field of such a type will pass validation as a string. See Field Data Types for a complete list of OLE Automation types.

  • When you click a field in the Select node tree, the field name is automatically added to the Field name box.

  • When you click a field in the Select node tree, the node path to that field is automatically added to the Node path box.

  • You can only select fields from a schema created in or imported into BizTalk Editor when adding message fields.

  • Editing the node path manually is useful when you want to extract specific data from within a field. For example, if the field contains an array, you might want to retrieve just one item from the array and not the entire array. However, it is recommended that you refrain from manually editing the node path for your message specification.

  • You cannot select a node to add to the Message fields list. You can select only fields. A field also might be referred to as a leaf node. For example, you cannot select the Seller and Address nodes because they contain leaf nodes. The Name and Address fields can be selected because they are fields that do not contain additional nodes.

  • While waiting to receive a message from a message queue, some problems (such as invalid XML messages or insufficient authentication) will cause a dead letter queue to be dynamically created. The dead letter queue is specific to a COM+ application. The dead letter queue will be given the name .\private$\ApplicationName.DeadLetter. For example, if a message containing invalid XML arrives on the queue, and you have specified on the XML Translation Information page of the XML Communication Wizard that the XLANG Scheduler Engine is expecting XML messages from the queue, any invalid XML messages will be moved to .\private$\ApplicationName.DeadLetter.

  • If you design two different XLANG schedules to receive different messages from the same message queue, it is possible that a message might be processed by the wrong XLANG schedule instance. To avoid this problem, use one message queue for each type of message that is received by an XLANG schedule instance.

Related Topics

Asynchronous Communication

Synchronous and Asynchronous Communication

Synchronous Communication

Using the Method Communication Wizard


Asynchronous Communication

An asynchronous message is put into a message queue or a BizTalk Messaging channel, and the XLANG schedule continues. It does not wait for a response.

The only messages available for use in an asynchronous communication are XML messages. All XML messages are available for use and can be specified for more than one port. You cannot use any of the synchronous message pairs that are created by using the Method Communication Wizard.

Asynchronous Messages

When you create an asynchronous communication, a Message is created on the Data page. The Message corresponds to information that is sent or received in the communication flow. The Message contains required system fields and any additional specification fields that you want.

The Message schema is shown in the following example:

Message name
__Sender__   string
Document   string
   Field 1   Data type 1
   Field 2   Data type 2
   Field n   Data type n

The following illustration shows a message named Message_1. The system fields __Sender__ and Document are automatically provided and are present in all asynchronous messages. This message also contains two user-selected specification fields.

A message that contains two system-added fields and two user-selected specification fields

You can add a specification field by using the Field Selection dialog box that is in the XML Communication Wizard. In the Field Selection dialog box, you can select a specification field by clicking a node in the Select node tree. When you click a node, the node path is added to the Node path box. You must select a leaf node. A leaf node is a node with no children. In the following illustration, the node Name is a leaf node; however, the node Address is not a leaf node.

A node path is also known as an XPath. You can use the node path as it is selected, or you can type additional criteria to the path. For example, if you select a node that contains an array, you might want to specify a specific index in the array to retrieve, rather than retrieving the entire array.

Note

  • If you choose to send or receive an XML message as a string, the Message shape that is created on the Data page for this message contains a field named StringData, and you cannot add specification fields to this message.

The following illustration shows the Field Selection dialog box.

The Field Selection dialog box

Note

  • For more information about selecting specification fields and using node paths, see the following topics:
    • Create and Validate Specifications

    • Node Path Fields

    • Send or receive asynchronous messages

    • Using the XML Communication Wizard

Related Topics

Create and Validate Specifications

Dehydration and Rehydration

Node Path Fields

Persistence

Send or receive asynchronous messages

Synchronous and Asynchronous Communication

Using the XML Communication Wizard


Compiling XLANG Schedules

When you have completed an XLANG schedule drawing, you can compile the drawing into an executable XLANG schedule. Before you compile the drawing, make sure the flow of data between messages has been defined on the Data page. An XLANG schedule describes the business process and the binding of that process to an implementation technology.

BizTalk Orchestration Designer is designed to provide as much useful information as possible when a problem in your XLANG schedule is discovered during the compilation process. If BizTalk Orchestration Designer encounters an error, it highlights the shape that contains the error, displays an error message, and cancels the compilation of the XLANG schedule.

During compilation, BizTalk Orchestration Designer examines each shape to determine if it is complete and correct. The XLANG Scheduler Engine processes the Begin shape on the Business Process page first, and then descends recursively through the entire drawing. If the XLANG Scheduler Engine encounters an error, the error typically occurs when the business process flows to a shape in a deeply nested position. To report the error, the XLANG Scheduler Engine constructs an appropriate error message. Then, as the XLANG Scheduler Engine returns up through the stack, each method has an opportunity to concatenate its own error message to the original error message. If none of the methods concatenates an error message to the original error message, the top-level compilation method adds the following generic error message:

Failed to process the XLANG schedule.

The compiled XLANG schedule contains a globally unique identifier (GUID) that matches the XLANG identity property of the Begin shape. This identification can be used to correlate a version of the XLANG schedule drawing with the XLANG schedule that generated it.

Note

  • It is highly recommended that you review the How to Perform BizTalk Orchestration Designer Tasks section for task-specific information about using BizTalk Orchestration Designer to create XLANG schedule drawings and compile them into executable XLANG schedules.

Related Topics

Compile and Debug XLANG Schedules

Compile an XLANG schedule drawing into an XLANG schedule

Debugging XLANG Schedules


Debugging XLANG Schedules

XLANG Event Monitor is a tool that you can use to monitor running XLANG schedule instances. For specific information about using XLANG Event Monitor, see the associated Readme.htm file. Both XLANG Event Monitor (XLANGMon.exe) and the readme installed by the Microsoft BizTalk Server 2002 Setup Wizard are located in the following installation directory: \Program Files\Microsoft BizTalk Server\SDK\XLANG Tools.

XLANG Event Monitor includes the following features:

  • It displays the XLANG Scheduler Engine working in real time.

  • After the initial enumeration of the running schedules, it monitors events. XLANG Event Monitor can be used to suspend and stop running instances.

  • It has a multiple-document interface (MDI)-like user interface that enables you to simultaneously view multiple instance traces.

  • It can simultaneously monitor selected applications on multiple computers.

  • It provides separate recording and viewing filters.

Related Topics

Compile and Debug XLANG Schedules

Compiling XLANG Schedules

Monitor Running XLANG Schedules

Orchestration Services Error Messages


Running XLANG Schedules

When installing BizTalk Orchestration Designer, several COM+ applications are installed and configured within Microsoft Windows 2000 Component Services, including the XLANG Scheduler COM+ application. This application hosts a default instance of the XLANG Scheduler Engine. Each new COM+ application created in Component Services has an XLANG tab on the Properties dialog box. On the XLANG tab you can enable the new COM+ application to host the XLANG Scheduler Engine. The specific COM+ application in which a new XLANG schedule will execute can be determined through the moniker syntax used to activate an instance of an XLANG schedule.

The XLANG Scheduler Engine controls the activation, execution, dehydration, and rehydration of running XLANG schedule instances. To activate an XLANG schedule, you can create a small application that passes the moniker of an XLANG schedule to the XLANG Scheduler Engine. The XLANG Scheduler Engine performs the actions within the XLANG schedule and continues the business process sequence until it becomes necessary to dehydrate the XLANG schedule. Dehydrating an XLANG schedule occurs when the XLANG Scheduler Engine expects to wait for more than three minutes to receive a message. When the message arrives, the XLANG Scheduler Engine rehydrates the XLANG schedule instance and continues to perform the actions in the business process sequence until the schedule either completes or the XLANG Scheduler Engine has to wait for another message. To support dehydration, you must have a persistence database configured. The recommended network library is TCP/IP.

To display Microsoft Windows 2000 Component Services information, perform the following procedure:

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Right-click the COM+ application you want.

    The Properties dialog box appears.

The XLANG tab on the Properties dialog box displays the following options:

  • This application is a host for XLANG schedule instances. If enabled, this COM+ application might activate instances of XLANG schedules. To direct the activation of a schedule instance to a particular COM+ application, use a moniker form that includes the name of the application. Check this option when you want the application to serve as a host for the XLANG Scheduler Engine.

  • Configuring the DSN for Persistence. In this area you can configure Microsoft SQL Server to support the dehydration and rehydration of long-running business processes:
    • Create DSN creates the ODBC data source name (DSN) for the COM+ application hosting the XLANG Scheduler Engine. A file DSN stores information about a database connection in a file. The file has the extension .dsn and by default is stored in the \Program Files\Common Files\ODBC\Data Sources directory. Click the Create DSN button to start the DSN Wizard.

    • Configure DSN opens the ODBC Data Source Administrator to manage the data source for XLANG schedules in this COM+ application.

    • Initialize Tables creates the tables that are needed to support persistence in the SQL Server database you have defined.

    Important

    • The data source name configured in the XLANG Scheduler Properties dialog box must be the same as the name of the COM+ application.
  • Controlled shutdown. In this area you can select a valid way to shut down the COM+ applications hosting XLANG schedule instances:
    • All XLANG Applications shuts down all COM+ applications that are hosting running XLANG schedule instances.

    Note

    • If you have selected an application other than the default application, This XLANG Application will be displayed.
  • Restart dehydrated XLANG applications. In this area you can manage dehydrated XLANG applications:
    • All XLANG Applications rehydrates all COM+ applications that are hosting XLANG schedule instances and, if possible, continues to run them.

Important

  • Do not right-click the COM+ application to shut down running instances of an XLANG schedule. This will leave COM components loaded in memory instead of unloading them correctly. Instead, use the Controlled Shutdown area of the XLANG tab in the properties for the XLANG Scheduler COM+ application.

Notes

  • When using the client for Microsoft Windows 2000 Terminal Services to initiate an XLANG schedule, the COM+ application hosting the XLANG Scheduler Engine must have its identity set to a valid Windows 2000 user or group name. The identity of the COM+ application is set on the Identity page of the properties dialog box for that application. The identity cannot be set to interactive when using the XLANG Scheduler Engine through a session hosted by Terminal Services.

  • For task-specific information about running an XLANG schedule, see Run an XLANG Schedule.

The following topics are covered in this section:

  • Moniker Syntax

  • Creating an Instantiating Application


Moniker Syntax

Monikers are used to create new XLANG schedule instances or to refer to an existing XLANG schedule instance. In either case, you can refer to a specific port within the schedule instance. Monikers determine which COM+ application will host the XLANG Scheduler Engine.

To create a new instance of an XLANG schedule, a moniker for the XLANG schedule must be passed to the COM+ application. The COM+ application forwards the moniker to the XLANG naming service for resolution and to activate the XLANG schedule instance with an instance of the XLANG Scheduler Engine. The following code sample shows the general syntax for monikers:

sked://[HostName][!GroupManager][/FilePath][/PortName]

Each segment of the moniker syntax is optional, depending on what type of object you want to instantiate. The following table lists and describes each of the moniker syntax segments.

Moniker syntax segment | Description | Examples
HostName | The host name of the computer running the XLANG Scheduler Engine. This is also referred to as the XLANG System Manager. If omitted, localhost is used as the default value. This name is not case sensitive. | sked:// sked://MyServer
GroupManager | The XLANG Scheduler Engine group manager that is used to manage XLANG schedule instances. The name of the group manager is the same as the COM+ application that is designated as an XLANG host. If omitted, XLANG Scheduler is used as the default value. This name is case sensitive and can contain spaces. | sked:/// sked://AnotherServer!/ sked://AnotherServer!MyGroup/
FilePath | The path to an XLANG schedule file (.skx) to be activated. This value is not case sensitive. | sked://host1!MyGrp/C:\basic.skx sked:///C:\basic.skx
PortName | The name of a port that is bound to a COM or Windows Script Component on an XLANG schedule. This name is case sensitive. | sked:///C:\basiccom.skx/portA

Moniker syntax can be used to refer to an existing XLANG schedule instance, to start an XLANG schedule, or to establish a communication channel with a particular port on the new XLANG schedule instance.

Monikers that refer to an XLANG schedule instance are created by the XLANG Scheduler Engine and are made available by creating a connection between the Port References shape and messages that are sent by the XLANG schedule. The exact form of the port reference depends on which implementation technology the port is bound to and the data type of the target message field. Ports that are bound to Message Queuing or BizTalk Messaging Services can only be connected to fields of data type String. The target field contains the name of the queue or messaging endpoint that is bound to the port in the current XLANG schedule instance.

Ports bound to COM components can be connected to fields of data type String, Object, or Unknown. If the target field is of data type String, a moniker is created that refers to a port in the current XLANG schedule instance. This moniker is durable. It can be resolved by using the GetObject function, and the moniker remains valid after a system restart. If the target field is of data type Object or Unknown, a COM reference to the port instance is passed to the Message shape. If this kind of reference is passed to an external component, it is not valid after a system restart.

The moniker to reference a running XLANG schedule instance can be obtained from the XLANG schedule instance object, as shown in the following Microsoft Visual Basic code:

Dim oSchedule as IWFWorkflowInstance
Set oSchedule = GetObject("sked:///C:\temp\myschedule.skx")
dim sMoniker as string
sMoniker = oSchedule.FullyQualifiedName

Related Topics

Creating an Instantiating Application

Running XLANG Schedules


Creating an Instantiating Application

An instantiating application passes a moniker for the completed XLANG schedule file to the XLANG Scheduler Engine by using the COM function GetObject. The following Microsoft Visual Basic code shows one way to do this:

Dim objExecute As object
Dim strURL as string

strURL = "sked:///c:\temp\myschedule.skx"

' This instantiates an XLANG schedule and enables the XLANG Scheduler
' Engine to execute the XLANG schedule.
Set objExecute = GetObject(strURL)

If you did not specify a port in the moniker, the Port property of the object that is returned by the GetObject function enables you to obtain a reference to a port that is bound to a COM component. Similarly, the FullPortName property enables you to obtain the full, durable name of a port bound to an implementation technology.

The following code shows how to obtain a proxy to a COM or Script port. This code sample continues from the previous code sample:

Dim oPort as Object
Set oPort = objExecute.Port("SchedulePortName")
Call oPort.ComponentMethodName(arg1,arg2,...argN)

Note

  • If the port is bound to a COM object that does not support a dual interface, the oPort variable must be declared with the appropriate class.

Related Topics

Moniker Syntax

Running XLANG Schedules


Pooling XLANG Schedules

When traffic is high and many schedule instances are active at once, you can make effective use of available resources by pooling your schedules. BizTalk Server takes advantage of COM object pooling, and enables you to restrict the number of active schedule instances. You can set the following properties on an object pool:

  • You can set a maximum number of schedule instances for a pool. When this maximum has been reached, no additional instances of schedules that use that pool are created until a schedule either completes or is dehydrated. The default maximum is 25 instances.

  • You can also set a timeout period on a pool. This is the length of time a schedule instance pending activation will wait for a slot to become available within its pool. The default timeout period is 30,000 milliseconds (30 seconds).

  • You can improve performance by setting a minimum pool size. The minimum size determines how many pooling objects will be maintained in memory, so that they do not have to be created on demand each time a schedule instance is activated in that pool. The default minimum is one object.

These settings might not be optimal for one or more of your pools; pooling settings should be configured to your particular needs to be most effective. For example, short-lived schedules with heavy traffic should generally be configured to run in an object pool with a relatively large maximum number of instances. A relatively large minimum number might help as well; if you expect steady traffic, having a number of objects created in advance will help performance. The timeout should be short and the messaging retry count high in this case. For a longer running schedule in decreased traffic, you might want to use a longer timeout and a smaller minimum and maximum of instances, as well as a lower messaging retry count.

Notes

  • You may assign more than one schedule to a pool if you like, but if you do this, be sure that the pool settings meet the needs of all of the schedules assigned to it.

  • Pooling does not present any backward compatibility issues. Schedules that do not have the pooled property set will get no pooling effects.

  • After a pooled schedule instance to which the user holds a reference completes execution, it will continue to occupy a place in the pool until the reference to that instance goes out of scope or is explicitly released, as shown in the following code sample:
    Set FSO = CreateObject("Scripting.FileSystemObject")
CurrentDirPath = FSO.GetAbsolutePathName(".")
SkedMoniker = "sked://localhost/" & CurrentDirPath & "\PoolingSample.skx"
While '(some condition)
    Set Sked = GetObject(SkedMoniker)
    '(some action)
    Set Sked = Nothing
Wend

Related Topic

Pool an XLANG schedule


Managing Session State

On the Advanced Properties page of the COM Component Binding Wizard, you can select a state management value for the level of persistence that your COM component supports. In the State management support area, select one of the following options:

  • Holds no state. This specifies that the XLANG Scheduler Engine will terminate the component instance if the schedule instance is dehydrated. If you select this setting, the XLANG Scheduler Engine will create a new component instance, if it is required, when the schedule is rehydrated.

  • Holds state, but doesn't support persistence. This specifies that the XLANG Scheduler Engine will be required to leave the component instance running until it is no longer needed in the schedule execution. If the system were to fail while the schedule instance was dehydrated, any state that had been held in this component would be lost.

  • Holds state, and does support persistence. This specifies that the XLANG Scheduler Engine will remove the component instance from memory, and then restore it to memory by calling either IPersistStream or IPersistStreamInit on the component during dehydration, and then again during rehydration.

Related Topic

Instance Management


Updating XLANG Schedules

There are two ways to update an XLANG schedule. You can overwrite the original XLANG schedule, or you can add a new XLANG schedule that will run concurrently with the original XLANG schedule.

To overwrite the original XLANG schedule, use BizTalk Orchestration Designer to create a new XLANG schedule drawing and then compile the XLANG schedule drawing as an XLANG schedule that has the same name as the original XLANG schedule. The XLANG schedule drawing is saved as an .skv file, which is a customized version of the Microsoft Visio 2000 file format. You can then compile the XLANG schedule drawing into an XLANG schedule, which is an XML-structured .skx text file that the XLANG Scheduler Engine understands. To update the original XLANG schedule, copy the new .skx file over the original .skx file.

To add a new XLANG schedule that will run concurrently with the original XLANG schedule, use BizTalk Orchestration Designer to create a new XLANG schedule drawing and compile the XLANG schedule drawing as an XLANG schedule with a new name. To ensure that the new XLANG schedule will be correctly activated, you must change the XLANG schedule instance activation mechanism to point to the new .skx file instead of pointing to the old .skx file. When you have completed this process, new requests for XLANG schedules will create instances of the new XLANG schedule.

Because all XLANG schedules and their components typically work on a per-instance basis, XLANG schedule instances that are in the process of executing the original schedule will continue to run to completion. This includes XLANG schedule instances that have been persisted because the source code of the original schedule has been saved. In this scenario, the execution path will continue to follow the original business process, and new requests for XLANG schedules will create instances of the new XLANG schedule.

Note

  • When an XLANG schedule uses an object with an interface that has changed, load the XLANG schedule drawing (the .skv file) into BizTalk Orchestration Designer and compile a new .skx file. This will update the binding information in the .skx file, enabling synchronization with the component's type library.


Why Perform BizTalk Orchestration Designer Tasks

This section provides a quick reference about why you perform BizTalk Orchestration Designer tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Use BizTalk Orchestration Designer
 To create drawings of business processes that can be compiled and run as XLANG schedules.
  • Open and Save XLANG Schedule Drawings
 To create, open, or save an XLANG schedule drawing of a business process.
View Pages, Shapes, and Stencils
View the Design Pages:
  • View the Business Process page
 To view a conceptual drawing of a business process.
  • View the Data page
 To view message fields, port fields, constants, and the flow of data between them.
  • 3View the Business Process and Data pages
 To get a concurrent view of both the Business Process and Data pages.
  • View Compensation for Transaction pages
 To view code that rolls back the results of a nested transaction.
  • View On Failure of Transaction pages
 To view error-handling code associated with a failed transaction.
View Shapes:
  • View Flowchart shapes
 To view only the Flowchart shapes that describe business processes.
  • View Flowchart and Communication shapes
 To view the Flowchart shapes that describe business processes and the connections between them.
  • View Flowchart, Communication, and Implementation shapes
 To view the Flowchart shapes that describe business processes, the Implementation shapes that describe ports, and the connections between them.
View Stencils:
  • View the Flowchart Stencil
 To view shapes that you can use to describe business processes.
  • View the Implementation Stencil
 To view shapes that you can use to implement communications ports between business processes.
  • Use Multiple Windows
 To open, tile, and cascade windows or change the window focus to view different pages of an XLANG schedule or different parts of the same page at the same time.
  • Use Annotations
 To add, edit, or format annotations to make descriptive notes about your business process.
  • Preview, Print, or Resize XLANG Schedule Drawings
 You can print out your XLANG schedule drawing, preview it before printing, or adjust the size of it.
  • Add, Delete, and Connect Shapes
 To place and logically connect shapes that represent actions in your XLANG schedule drawing.
  • Select a shape
 Selecting a shape enables you to edit shape properties, perform cut-and-paste operations with the shape, or create connections between shapes.
  • Connect two shapes
 To represent process and communication flow by connecting actions with other actions or with ports.
  • Use the Connector Tool
 Use this tool as a convenient way of drawing the connections between actions.
  • Align shapes along a vertical or a horizontal axis
 To align shapes vertically or horizontally to improve the look and clarity of a schedule drawing.
Set Conditional Properties:
  • Set Decision Conditions
 To add rules to a Decision shape or determine the order in which rules will be evaluated.
  • Set While Loop Conditions
 To add a rule to determine whether to continue execution of a while loop.
  • Preserve state in a while loop
 To specify whether or not to include messages used in each loop iteration in a saved XLANG schedule state.
Create Rules:
  • Create a rule
 To evaluate conditions in decisions and while loops within your business process.
  • Use the expression assistant
 To add the names of messages and fields to the script expression within a rule.
  • Add constants to a rule
 To use constants from the Data page within a script expression.
Set Concurrency Properties:
  • Create concurrent flows
 To create separate but concurrent logical flows, or forks, within your business process.
  • Set the Join Type property
 To specify whether or not you are requiring all concurrent processes to complete execution before continuing to the next action.
  • Join concurrent flows
 To synchronize concurrent actions so that they will proceed to a common action.
  • End a concurrent flow
 To terminate one concurrent flow so that it does not rejoin others.
Set Transaction Properties
Set Transaction Properties for an XLANG Schedule:
  • Set the transaction model
 To specify whether to allow transactions within the XLANG schedule itself or treat the schedule as a COM+ component, in which case the schedule can exist within the context of a COM+ transaction.
  • Set the transaction activation property
 To specify how your XLANG schedule will behave within the context of a COM+ transaction. You can have the schedule ignore COM+ transactions or participate in them, or you can require that the schedule will always run within a transaction or always create a new transaction within which to run.
Set Individual Transaction Properties:
  • Group actions and flows within a transaction
 To place shapes or flows within a Transaction shape so that they will be treated as one transaction.
  • Design nested transactions
 To place one transaction within another.
  • Create flows that enter and leave transactions
 To specify the flows that begin and end a transaction, and to connect actions with corresponding ports.
  • Name a transaction
 To assign a value to the Name property of a transaction.
  • Set the transaction Type property
 To specify whether the transaction is a timed transaction, a short-lived DTC-style transaction, or a long-running transaction.
  • Set the Timeout property
 To set the time, in seconds, that a transaction will be allowed to run before it aborts.
  • Set the Retry count property
 To set the number of times a process within a short-lived, DTC-style transaction will be rerun if it does not complete.
  • Set the Backoff time property
 To set the time interval between retries of a transaction.
  • Set the Isolation level property
 To specify the degree to which data in concurrent short-lived, DTC-style transactions is mutually available.
  • Set the Persist Schedule State property
 To specify whether or not a schedule's state will be persisted before a transaction begins.
Describe Component and Message Queuing Transaction Support:
  • Describe the level of transaction support in a COM component
 To specify whether transactions for this COM component are disabled, supported, not supported, required, or required to be new.
  • Describe the level of transaction support in a Windows Script Component
 To specify whether transactions for this Windows Script Component are disabled, supported, not supported, required, or required to be new.
  • Describe the transaction support provided by a message queue
 To specify whether or not transactions are required with this queue.
Set Error Handling Properties:
  • Abort a process flow
 If the application of a rule evaluates to an unexpected or incorrect value, you can choose to abort the flow of the process.
Enable Transaction Error Handling:
  • Enable On Failure error handling
 You enable this so that the XLANG schedule can run On Failure of Transaction code to efficiently handle failures within a transaction.
  • Enable Compensation error handling
 You enable this so that the XLANG schedule can run Compensation for Transaction code to roll back the results of a nested transaction.
Enable Component Error Handling:
  • Abort a transaction if a COM component returns a failure
 To specify whether a transaction should be aborted if a method call to a COM component returns a failure HRESULT.
  • Abort a transaction if a Windows Script Component returns a failure
 To specify whether a transaction should be aborted if a method call to a Windows Script Component returns a failure HRESULT.
Implement Ports:
  • Add an unbound port to an XLANG schedule drawing
 You can do this to add a port to a schedule before having to decide on the details of an implementation for the port.
  • Add a bound port to an XLANG schedule drawing
 To add a port implementation directly to the schedule.
  • Implement a port by using a COM component
 To use an existing COM component or application to perform an action.
  • Implement a port by using a Windows Script Component
 To use an existing Windows Script Component to perform an action.
  • Implement a port by using Message Queuing
 To enable the schedule to communicate with another schedule or application in a loosely coupled manner.
  • Implement a port by using BizTalk Messaging
 To enable your schedule to take advantage of BizTalk Messaging Services to carry out a communication.
  • Modify port implementation properties
 To modify a variety of properties that govern the type and behavior of your implementation.
Send or Receive Messages:
  • Establish the communication flow between an action and a port
 To create a flow of communication between an action in your business process and an external business process.
  • Send or receive synchronous messages
 To specify a synchronous flow of communication between an action in your business process and an external business process.
  • Send or receive asynchronous messages
 To specify an asynchronous flow of communication between an action in your business process and an external business process.
  • Modify the communication flow between an action and a port
 To specify whether a communication flow is synchronous or asynchronous.
  • Draw the Flow of Data between Messages
 You can describe data interactions by selecting messages, their fields, and ports and drawing the flow of data between them.
  • Use Constants
 Use constants as specified on the Data page to provide data for message fields.
Run XLANG Schedules
Compile and Debug XLANG Schedules:
  • Compile an XLANG schedule drawing into an XLANG schedule
 To create an executable XLANG schedule from the corresponding XLANG schedule drawing of a business process.
  • Run an XLANG schedule
 To carry out a business process; the basic action of BizTalk Server.
  • Pool an XLANG schedule
 To control the number of instances of an XLANG schedule that can be active in memory at any one time, to optimize resource usage.
  • Debug compiled Visual Basic components
 To set breakpoints, view code, and debug components built with Microsoft Visual Basic.
  • Refresh method signatures
 If you have changed any parameters of any available method calls, you use this procedure to make the method parameters available to the schedule.
  • Shut down all running XLANG schedules
 To modify COM components used by a schedule. If a schedule instance is running, the file containing the COM component will be locked.
Create and Configure an XLANG Schedule Host Application:
  • Create a COM+ application to host XLANG schedules
 If you have security, deployment, or configuration issues that make it advantageous to have a schedule run from within a COM+ application.
  • Configure a COM+ application to host XLANG schedules
 To set or modify a variety of COM+ application properties that will affect the performance and behavior of your hosting application.


How to Perform BizTalk Orchestration Designer Tasks

This section provides task-specific information about how to use BizTalk Orchestration Designer to create XLANG schedule drawings and compile them into executable XLANG schedules. This section also provides information about how to run an XLANG schedule. It is highly recommended that you review the Concepts section to fully understand all the features and capabilities of BizTalk Orchestration Designer.

The following topics are covered in this section:

  • Use BizTalk Orchestration Designer

  • Run XLANG Schedules

Note

  • The following conventions apply to transactions, ports, messages, rules, queues, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.


Use BizTalk Orchestration Designer

This section contains procedures that explain how to use BizTalk Orchestration Designer to design XLANG schedule drawings and how to compile them into XLANG schedules.

The following topics are covered in this section:

  • Open and Save XLANG Schedule Drawings

  • View Pages, Shapes, and Stencils

  • Add, Delete, and Connect Shapes

  • Set Conditional Properties

  • Set Concurrency Properties

  • Set Transaction Properties

  • Set Error Handling Properties

  • Implement Ports

  • Send or Receive Messages

  • Draw the Flow of Data Between Messages

Notes

  • If one or more of the files in the VBA folder have not been properly registered or have become corrupt, you might not be able to open BizTalk Orchestration Designer. This problem can result from uninstalling Microsoft Office.
    • If Office is not installed: On the Microsoft Office CD, browse to the Vba6.msi file, right-click it, and click Install.

    • If Office is installed: Open Microsoft Access, create a blank database, save it, and close Access.
  • If you hide the standard toolbar when using Microsoft Visio, you will not be able to see it upon opening Orchestration Designer. To see it, do the following:
    1. On the File menu, select Exit to close BizTalk Orchestration Designer. On the Start menu, point to Programs and click Microsoft Visio.

    2. On the View menu, point to Toolbars and click Standard.

    3. On the File menu, select Exit to close Visio.

    4. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Orchestration Designer.

      The toolbar appears.

  • After using BizTalk Orchestration Designer, some menus and toolbars will not be accessible upon opening Visio. You can use the context menu in Visio to customize toolbars and menus and reactivate the items you want.

International Issue

  • In some languages, certain characters might not display properly in BizTalk Orchestration Designer. To correct this, you can specify that Microsoft Visio 2002 must always use the system default font:
    1. Close BizTalk Orchestration Designer.

    2. On the Start menu, point to Programs and click Microsoft Visio.

    3. On the Tools menu, click Options.

      The Options dialog box appears.

    4. Click the Regional tab and, in the Document base font area, select Always use the system default font.

    5. Close Visio and open BizTalk Orchestration Designer.


Open and Save XLANG Schedule Drawings

The following procedures are covered in this section:

  • Create a new XLANG schedule drawing

  • Open an existing XLANG schedule drawing

  • Save an XLANG schedule drawing


Create a new XLANG schedule drawing

This procedure opens a new XLANG schedule drawing within the design window. The Business Process page is the default beginning design page. The Flowchart and Implementation stencils also open by default when you start a new drawing.

  • In BizTalk Orchestration Designer, on the File menu, click New.

Note

  • The file extension for an XLANG schedule drawing is .skv.

Related Topics

Open an existing XLANG schedule drawing

Save an XLANG schedule drawing


Open an existing XLANG schedule drawing

  1. In BizTalk Orchestration Designer, on the File menu, click Open.

    The Open XLANG Schedule Drawing dialog box appears.

  2. Browse to the XLANG schedule drawing that you want to open, click the drawing, and then click Open.

Notes

  • The file extension for an XLANG schedule drawing is .skv.

  • The file extension for an XLANG schedule is .skx. You cannot open an .skx file within BizTalk Orchestration Designer. To change or update an .skx file, open the source .skv file, make your changes, and then recompile the .skv file into an .skx file.

Related Topics

Create a new XLANG schedule drawing

Save an XLANG schedule drawing


Save an XLANG schedule drawing

  • In BizTalk Orchestration Designer, on the File menu, click Save.

Notes

  • When you save an XLANG schedule drawing, the drawing is saved with the default name DrawingX.skv, where X is a number that is appended to the drawing name. You can change the name of the file when you save the drawing.

  • You can also click Save As on the File menu. This option opens the Save XLANG Schedule Drawing As dialog box. You can:
    • Rename the file to another name.

    • Save the file in a different location.
  • The file extension for an XLANG schedule drawing is .skv.

  • The file extension for an XLANG schedule is .skx. You cannot open an .skx file within BizTalk Orchestration Designer. To change or update an .skx file, open the source .skv file, make your changes, and then recompile the .skv file into an .skx file.

Related Topics

Create a new XLANG schedule drawing

Open an existing XLANG schedule drawing


View Pages, Shapes, and Stencils

BizTalk Orchestration Designer provides several view options that you can use to maximize your drawing area, or to view specific shape or data relationships.

The following topics are covered in this section:

  • View the Design Pages

  • View Shapes

  • View Stencils

  • Use Multiple Windows

  • Use Annotations

  • Preview, Print, or Resize XLANG Schedule Drawings


View the Design Pages

The following procedures are covered in this section:

  • View the Business Process page

  • View the Data page

  • View the Business Process and Data pages

  • View Compensation for Transaction pages

  • View On Failure of Transaction pages

  • View a page

Related Topics

Use Multiple Windows

View Shapes

View Stencils


View the Business Process page

  • On the View menu, click Business Process Page.

Note

  • You can also click the Business Process tab at the bottom of the design pages.

Related Topics

Use Multiple Windows

View a page

View Compensation for Transaction pages

View On Failure of Transaction pages

View Shapes

View Stencils

View the Business Process and Data pages

View the Data page


View the Data page

  • On the View menu, click Data Page.

Note

  • You can also click the Data tab at the bottom of the design pages.

Related Topics

Use Multiple Windows

View a page

View Compensation for Transaction pages

View On Failure of Transaction pages

View Shapes

View Stencils

View the Business Process and Data pages

View the Business Process page


View the Business Process and Data pages

  • On the View menu, click Business Process and Data Pages.

Note

  • This view option opens two windows for the same XLANG schedule: a Business Process window and a Data window. This functionality is similar to that obtained by using the New Window option. For more information about opening multiple windows, see Use Multiple Windows.

Related Topics

Use Multiple Windows

View a page

View Compensation for Transaction pages

View On Failure of Transaction pages

View Shapes

View Stencils

View the Business Process page

View the Data page


View Compensation for Transaction pages

  • At the bottom of the design pages, click the Compensation for Transaction tab for the page that you want to view.

Notes

  • The parameter Transaction in the name of the page is replaced with the name of the transaction with which the error-handling process is associated.

  • For information about how to add a Compensation for Transaction page to an XLANG schedule drawing, see Enable Compensation error handling.

Related Topics

Use Multiple Windows

View a page

View On Failure of Transaction pages

View Shapes

View Stencils

View the Business Process and Data pages

View the Business Process page

View the Data page


View On Failure of Transaction pages

  • At the bottom of the design pages, click the On Failure of Transaction tab for the page that you want to view.

Notes

  • The parameter Transaction in the name of the page is replaced with the name of the transaction with which the error-handling process is associated.

  • For information about how to add an On Failure of Transaction page to an XLANG schedule drawing, see Enable On Failure error handling.

Related Topics

Use Multiple Windows

View a page

View Compensation for Transaction pages

View Shapes

View Stencils

View the Business Process and Data pages

View the Business Process page

View the Data page


View a page

  • Click the tab for the page that you want to view.

Note

  • Tabs for each page are located at the bottom of the design pages.

Related Topics

Use Multiple Windows

View Compensation for Transaction pages

View On Failure of Transaction pages

View Shapes

View Stencils

View the Business Process and Data pages

View the Business Process page

View the Data page


View Shapes

The following procedures are covered in this section:

  • View Flowchart shapes

  • View Flowchart and Communication shapes

  • View Flowchart, Communication, and Implementation shapes

Related Topics

View Stencils

View the Design Pages


View Flowchart shapes

If you use this option, only Flowchart shapes and the connections between them are displayed on the design page. This option hides all ports, port messages, implementations, and connections between ports and actions or between ports and implementations.

  • On the View menu, click Flowchart Shapes.

Notes

  • This view option cannot be used on the Data page.

Related Topics

View Flowchart and Communication shapes

View Flowchart, Communication, and Implementation shapes

View Stencils

View the Design Pages


View Flowchart and Communication shapes

If you use this option, Flowchart shapes and the connections between them are displayed on the design page. Ports, port messages, and the connections between ports and actions are also displayed. This option hides all implementations, and connections between ports and implementations.

  • On the View menu, click Flowchart and Communication Shapes.

Notes

  • This view option cannot be used on the Data page.

Related Topics

View Flowchart, Communication, and Implementation shapes

View Flowchart shapes

View Stencils

View the Design Pages


View Flowchart, Communication, and Implementation shapes

  • On the View menu, click Flowchart, Communication, and Implementation Shapes.

Notes

  • All shapes and the connections between them are displayed.

  • This view option cannot be used on the Data page.

Related Topics

View Flowchart and Communication shapes

View Flowchart shapes

View Stencils

View the Design Pages


View Stencils

The following procedures are covered in this section:

  • View the Flowchart stencil

  • View the Implementation stencil

Related Topics

View Shapes

View the Design Pages


View the Flowchart stencil

  • On the View menu, point to Stencils and click Flowchart to toggle the Flowchart stencil on or off.

Related Topics

View Shapes

View the Design Pages

View the Implementation stencil


View the Implementation stencil

  • On the View menu, point to Stencils and click Implementation to toggle the Implementation stencil on or off.

Related Topics

View Shapes

View the Design Pages

View the Flowchart stencil


Use Multiple Windows

The following procedures are covered in this section:

  • Open a new window

  • Tile windows

  • Cascade windows

  • Change the window focus

Related Topic

View the Design Pages


Open a new window

  • On the Window menu, click New Window.

Note

  • Multiple windows provide additional views of the same XLANG schedule. This enables you to:
    • View different pages of the same XLANG schedule at the same time. For example, you can open views for the Business Process page, the Data page, and a Compensation for Transaction page.

    • View different parts of the same page of an XLANG schedule at the same time. For example, in one view you can zoom in to see a specific set of shapes in the XLANG schedule; in another view you can zoom out to see the whole schedule.

Related Topics

Cascade windows

Change the window focus

Tile windows

View the Design Pages


Tile windows

Tiling the window views enables you to see several windows at the same time.

  • On the Window menu, click Tile.

Notes

  • Multiple windows provide additional views of the same XLANG schedule. This enables you to:
    • View different pages of the same XLANG schedule at the same time. For example, you can open views for the Business Process page, the Data page, and a Compensation for Transaction page.

    • View different parts of the same page of an XLANG schedule at the same time. For example, in one view you can zoom in to see a specific set of shapes in the XLANG schedule; in another view you can zoom out to see the whole schedule.

Related Topics

Cascade windows

Change the window focus

Open a new window

View the Design Pages


Cascade windows

Cascading the window views enables you to bring one window to the front of the screen. You can click the title bars of the other windows to bring them to the front of the screen.

  • On the Window menu, click Cascade.

Notes

  • Multiple windows provide additional views of the same XLANG schedule. This enables you to:
    • View different pages of the same XLANG schedule at the same time. For example, you can open views for the Business Process page, the Data page, and a Compensation for Transaction page.

    • View different parts of the same page of an XLANG schedule at the same time. For example, in one view you can zoom in to see a specific set of shapes in the XLANG schedule; in another view you can zoom out to see the whole schedule.

Related Topics

Change the window focus

Open a new window

Tile windows

View the Design Pages


Change the window focus

  • On the Window menu, click the name of the window to which you want to switch the focus.

Notes

  • The name of a window is the name of the XLANG schedule with the name of a design page appended to it (for example, Schedule1.skv:Business Process or Schedule1.skv:Data).

  • Multiple windows provide additional views of the same XLANG schedule. This enables you to:
    • View different pages of the same XLANG schedule at the same time. For example, you can open views for the Business Process page, the Data page, and a Compensation for Transaction page.

    • View different parts of the same page of an XLANG schedule at the same time. For example, in one view you can zoom in to see a specific set of shapes in the XLANG schedule; in another view you can zoom out to see the whole schedule.

Related Topics

Cascade windows

Open a new window

Tile windows

View the Design Pages


Use Annotations

The following procedures are covered in this section:

  • Add annotations

  • Edit annotations

  • Format text in annotations

  • Delete annotations


Add annotations

  1. In BizTalk Orchestration Designer, on the toolbar, click the Text Tool ( Text tool) button.

  2. Use the mouse pointer to drag over the area where you want to create an annotation.

  3. Type the annotation.

Notes

  • To turn off the Text Tool, on the toolbar, click the Pointer Tool ( Pointer Tool button) button.

  • Because BizTalk Orchestration Designer uses a custom Microsoft Visio interface, the Text Tool button offers two options. The functionality of both buttons is identical:
    • The Text Tool ( Text button) button

    • The Text Block Tool ( Text block button) button

Related Topics

Delete annotations

Edit annotations

Format text in annotations


Edit annotations

  1. In BizTalk Orchestration Designer, on the toolbar, click the Text Tool ( Text tool) button.

  2. Click the annotation that you want to edit.

  3. Edit the annotation.

Notes

  • To turn off the Text Tool, on the toolbar, click the Pointer Tool ( Pointer Tool button) button.

  • Because BizTalk Orchestration Designer uses a custom Microsoft Visio interface, the Text Tool button offers two options. The functionality of both buttons is identical:
    • The Text Tool ( Text button) button

    • The Text Block Tool ( Text block button) button

Related Topics

Add annotations

Delete annotations

Format text in annotations


Format text in annotations

  1. In BizTalk Orchestration Designer, on a design page, select one or more annotations that you want to format.

  2. On the Format menu, click Text.

    The Text dialog box appears. This dialog box offers several options for the size, font, and appearance of text.

  3. Select the options that you want to use and click OK.

Notes

  • These options are applied to the annotations that you highlight in the XLANG schedule drawing, and to any new annotations that you create.

  • You cannot format annotations when the Text Tool is turned on.

  • To select an annotation, click it. To select more than one annotation, press and hold the SHIFT key, and then click the annotations that you want to select.

Related Topics

Add annotations

Delete annotations

Edit annotations


Delete annotations

  • In BizTalk Orchestration Designer, on a design page, click the annotation that you want to delete and press DELETE.

Note

  • You must turn off the Text Tool before you can delete an annotation from the XLANG schedule drawing.

Related Topics

Add annotations

Format text in annotations


Preview, Print, or Resize XLANG Schedule Drawings

The following procedures are covered in this section:

  • Use Print Preview

  • Print an XLANG schedule drawing

  • Resize an XLANG schedule drawing


Use Print Preview

  • On the File menu, click Print Preview.

Note

  • If you change the Layout Orientation option from Landscape to Portrait, you will receive the following message:

    One or more drawing pages are oriented differently from the printed page setup. Click OK to print your drawing across multiple pages. To match orientations, change the printed page orientation.

    If you click OK and make this change, Print Preview might display the following behavior:

    • When you click Next Tile to pan pages forward, and then click Previous Tile to pan back to the first page, some shapes might appear in Print Preview as if they are not on the page. This display is harmless. The actual XLANG schedule will print correctly across several pages.

Related Topics

Print an XLANG schedule drawing

Resize an XLANG schedule drawing


Print an XLANG schedule drawing

  1. On the File menu, click Print.

    The Print dialog box appears.

  2. Set any options that you want and click Print.

Note

  • Confirm that a printer is installed before you attempt to print an XLANG schedule drawing.

Related Topics

Resize an XLANG schedule drawing

Use Print Preview


Resize an XLANG schedule drawing

  1. In BizTalk Orchestration Designer, on the View menu, click Whole Page.

  2. Press and hold CTRL, and then move the mouse pointer to the edge of the page.

    The pointer changes shape to a double arrow at the edge of the page.

  3. Click and drag the edge of the page to resize it.

Related Topics

Print an XLANG schedule drawing

Use Print Preview


Add, Delete, and Connect Shapes

The following procedures are covered in this section:

  • Add shapes

  • Name shapes

  • Delete shapes

  • Delete unused ports and messages

  • Connect Shapes


Add shapes

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

  • In BizTalk Orchestration Designer, on the Flowchart stencil, click a shape and drag it to the design page.

Notes

  • For information about adding Implementation shapes to an XLANG schedule drawing, see Implement Ports.

  • You cannot add shapes to the Data page. New messages are created automatically on the Data page each time an action is connected to a port.

Related Topics

Connect Shapes

Delete shapes

Delete unused ports and messages

Name shapes

View the Flowchart stencil


Name shapes

  1. In BizTalk Orchestration Designer, on a design page, right-click a shape and click Properties.

    The Shape Properties dialog box appears.

  2. In the Name box, type a name.

Notes

  • The Name property of each shape contains a default value that is the name of the shape with a number appended to the name, for example, Action 1. You can replace the default value with a name of your choice.

  • You cannot name any of the following shapes: Abort, Begin, Decision, End, Fork, Join, and While.

  • You can name the following shapes: Action, Transaction, Port, Message, and Rule.

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • Transaction names in single-byte character sets must be less than or equal to 16 characters in length. Transaction names in double-byte character sets must be less than or equal to 8 characters in length.

  • Actions are exempt from all naming conventions except the 32-character size limit.

Related Topics

Add shapes

Connect Shapes

Delete shapes

Delete unused ports and messages


Delete shapes

  • Click the shape that you want to delete and press DELETE.

Notes

  • You can delete a connection between two shapes by clicking the connection and pressing DELETE.

  • If a shape has connections to other shapes when you delete the shape, all connections are also deleted.

  • Any shapes that are enclosed within a transaction are deleted when you delete the transaction.

  • You can delete a BizTalk Messaging or Message Queuing implementation without deleting the ports to which these implementations are connected.

  • When you delete a COM component or Windows Script Component implementation, the ports to which they are connected are also deleted.

  • You can delete a message by clicking the message that is contained within a port and pressing DELETE. The associated message is deleted on the Data page.

    You can also delete messages from the Data page. For more information, see Delete a message.

  • You cannot delete rules by using the delete procedure. For more information about deleting rules, see the following topics:
    • Delete a rule from a decision

    • Delete a rule from a while loop

    • Delete unused rules

Related Topics

Add shapes

Connect Shapes

Delete a message

Delete a rule from a decision

Delete a rule from a while loop

Delete unused ports and messages

Delete unused rules

Name shapes


Delete unused ports and messages

This procedure deletes all unused ports, and any messages that the ports contain, from the XLANG schedule drawing. The corresponding messages on the Data page are also removed.

  • In BizTalk Orchestration Designer, on the Tools menu, click Delete Unused Ports and Messages.

Related Topics

Add shapes

Connect Shapes

Delete shapes

Name shapes


Connect Shapes

The following procedures are covered in this section:

  • Select a shape

  • Connect two shapes

  • Use the Connector Tool

  • Align shapes along a vertical or horizontal axis

Related Topics

Add shapes

Delete shapes

Delete unused ports and messages

Name shapes


Select a shape

Selecting a shape enables you to:

  • Drag control handles ( Control handle) from that shape to other shapes.

  • Edit available shape properties.

  • Cut, copy, paste, clear, and duplicate shapes.

Not all of these options are available for every shape.

  • In BizTalk Orchestration designer, on a design page, click the shape that you want to select.

    The shape that you select is surrounded with a green dashed border. Any control handles ( Control handle) available to that shape are enabled.

Note

  • If you copy an Action shape that is connected to a Port shape, the copy of that action also has a connection to the same port.

Related Topics

Add shapes

Connect two shapes

Delete shapes

Use the Connector Tool


Connect two shapes

  1. To connect two shapes, select the first shape.

    The shape that you select is surrounded with a green dashed border. Any control handles ( Control handle) available to that shape are enabled.

  2. Drag the appropriate control handle to the connection point ( Connection point) of the second shape.

  3. When the connection point is highlighted with a red box ( Active connection point), release the mouse button to set the connection.

Notes

  • Process flows are connected from the top and bottom connection points and control handles on shapes.

  • Communication flows are connected from the right control handle of an Action shape to the left connection point of a Port shape.

  • You also can use the Connector Tool to connect shapes. For more information, see Use the Connector Tool.

Related Topics

Add shapes

Delete shapes

Select a shape

Use the Connector Tool


Use the Connector Tool

  1. On the toolbar, click the Connector Tool ( Connector Tool button)) button.

  2. Hover over a control handle ( Control handle) that is on the shape from which you want to create a connection.

    The control handle is outlined with a red box to indicate that you can drag it.

  3. Press and hold the mouse button to drag the control handle from the shape to a connection point ( Connection point) on the shape to which you want to create the connection.

  4. When the connection point on the shape is outlined with a red box ( Active connection point), release the mouse button to establish the connection.

Notes

  • To turn off the Connector Tool, on the toolbar, click the Pointer Tool ( Pointer Tool button) button.

  • It is recommended that you use the Pointer Tool to connect Action shapes to Port shapes. If you use the Connector Tool to create a connection between an action and a port bound to a COM or script component, any subsequent activation of the corresponding component binding wizard will require that the connection be recreated, even if no properties have changed.

  • You can add shapes to a page and perform other operations when the Connector Tool is enabled. However, you might receive an error message. The error message is not valid, and it is harmless. This false error will be corrected in future releases of Microsoft Visio. If you receive this error message, click OK and continue. The text of the message is as follows:

    Visio internal error: #-1

    Action 1246: Drop On Page

    First try closing and reopening the file. Next try restarting Visio.

Related Topics

Add shapes

Connect two shapes

Delete shapes

Select a shape


Align shapes along a vertical or horizontal axis

  1. In BizTalk Orchestration Designer, on a design page, drag the mouse pointer around the shapes that you want to align along an axis.

  2. On the toolbar, click the Align Shapes ( Align shapes button) button.

    The Align Shapes dialog box appears.

  3. In one of the following areas, click the alignment that you want to use:
    • In the Up/Down alignment area, click one of the following buttons:

      Horizontal-Top Alignment button Horizontal-Top Alignment

      Horizontal-Center Alignment button Horizontal-Center Alignment

      Horizontal-Bottom Alignment button Horizontal-Bottom Alignment

    • In the Left/Right alignment area, click one of the following:

      Vertical-Left Alignment button Vertical-Left Alignment

      Vertical-Center Alignment button Vertical-Center Alignment

      Vertical-Right Alignment button Vertical-Right Alignment

Notes

  • You must select shapes on a design page to enable the Align Shapes button.

  • It is recommended that you align shapes along one axis only. Aligning shapes along both axes simultaneously might result in shapes being placed on top of each other. Press CTRL+Z to undo any changes that you do not want.

  • In the Align Shapes dialog box, the Disable Alignment ( Disable Alignment button) button clears an alignment selection.

  • The Create guide and glue shapes to it check box is always unavailable.

  • You can press and hold the SHIFT key, and then click several shapes to select them.


Set Conditional Properties

The following topics are covered in this section:

  • Set Decision Conditions

  • Set While Loop Conditions

  • Create Rules

Related Topic

Designing Rules


Set Decision Conditions

The following procedures are covered in this section:

  • Add a rule to a decision

  • Edit a rule in a decision

  • Delete a rule from a decision

  • Determine the evaluation order of rules

Related Topics

Create Rules

Designing Rules


Add a rule to a decision

  1. In BizTalk Orchestration Designer, on a design page, right-click the Decision shape for which you want to add a rule and click Add Rule.

    The Add Rule dialog box appears.

  2. Click one of the following options:
    • Create a new rule

      Click OK. The Rule Properties dialog box appears.

      For information about creating rules, see Create Rules.

    • Add an existing rule

      In the Available rules list, click the rule that you want to add and click OK.

      The Add Rule dialog box closes, and the rule is added to the decision.

Notes

  • The first time you add a rule to an XLANG schedule drawing, clicking Add Rule opens the Rule Properties dialog box. The Add Rule dialog box appears only if you have one or more previously created rules that you can add to a decision. For more information about the Rule Properties dialog box, see Create Rules.

  • You can also add a rule to a decision by right-clicking a Decision shape, clicking Properties, and then clicking Add.

Related Topics

Create Rules

Delete a rule from a decision

Designing Rules

Determine the evaluation order of rules

Edit a rule in a decision


Edit a rule in a decision

  1. In BizTalk Orchestration Designer, on a design page, right-click a Decision shape and click Properties.

    The Decision Properties dialog box appears.

  2. Click the rule that you want to edit and click Edit.

    The Rule Properties dialog box appears.

  3. Make the changes that you want and click OK.

    For more information about the Rule Properties dialog box, see Create Rules.

  4. To edit another rule, click the rule and click Edit.

    –Or–

    To close the Decision Properties dialog box, click OK.

Notes

  • In the Decision Properties dialog box, you can also add a rule by clicking Add.

  • You can also edit a rule by right-clicking a rule that is contained within a Decision shape and clicking Properties. This action opens the Rule Properties dialog box.

Related Topics

Add a rule to a decision

Create Rules

Delete a rule from a decision

Designing Rules

Determine the evaluation order of rules


Delete a rule from a decision

  1. In BizTalk Orchestration Designer, on a design page, right-click the Decision shape for which you want to delete a rule and click Properties.

    The Decision Properties dialog box appears.

  2. Click the rule that you want to delete and click Delete.

Related Topics

Add a rule to a decision

Create Rules

Designing Rules

Determine the evaluation order of rules

Edit a rule in a decision


Determine the evaluation order of rules

  1. In BizTalk Orchestration Designer, on a design page, right-click the Decision shape and click Properties.

    The Decision Properties dialog box appears.

  2. Click the rule for which you want to change the evaluation order.

  3. In the Order area, click the Up or Down arrow to move the rule to change the order in which it appears in the list.

Note

  • It is recommended that you order the rules in order of highest priority first. Rules are executed in sequence until a rule evaluates to TRUE. The process flow for the first rule that evaluates to TRUE is followed. If no rules evaluate to TRUE, the Else process flow is followed.

Related Topics

Add a rule to a decision

Create Rules

Delete a rule from a decision

Designing Rules

Edit a rule in a decision


Set While Loop Conditions

The following procedures are covered in this section:

  • Add a rule to a while loop

  • Edit a rule in a while loop

  • Delete a rule from a while loop

  • Preserve state in a while loop

Related Topics

Create Rules

Designing Rules


Add a rule to a while loop

  1. In BizTalk Orchestration Designer, on a design page, right-click the While shape for which you want to add a rule and click Add Rule.

    The Add Rule dialog box appears.

  2. Click one of the following options:
    • Create a new rule

      Click OK. The Rule Properties dialog box appears.

      For information about creating rules, see Create Rules.

    • Add an existing rule

      In the Available rules list, click the rule that you want to add and click OK.

      The Add Rule dialog box closes and the rule is added to the while loop.

Notes

  • The first time you add a rule to an XLANG schedule drawing, clicking Add Rule opens the Rule Properties dialog box. The Add Rule dialog box appears only if you have one or more previously created rules that you can add to a while loop. For more information about the Rule Properties dialog box, see Create Rules.

  • You can add only one rule to a while loop.

Related Topics

Create Rules

Delete a rule from a while loop

Designing Rules

Edit a rule in a while loop

Preserve state in a while loop


Edit a rule in a while loop

  1. In BizTalk Orchestration Designer, on a design page, right-click the rule that is contained within a While shape and click Properties.

    The Rule Properties dialog box appears.

  2. Make the changes that you want and click OK.

    For more information about the Rule Properties dialog box, see Create Rules.

Related Topics

Add a rule to a while loop

Create Rules

Delete a rule from a while loop

Designing Rules

Preserve state in a while loop


Delete a rule from a while loop

  • In BizTalk Orchestration Designer, on a design page, right-click the While shape for which you want to delete a rule and click Delete Rule.

Related Topics

Add a rule to a while loop

Create Rules

Designing Rules

Edit a rule in a while loop

Preserve state in a while loop


Preserve state in a while loop

  1. In BizTalk Orchestration Designer, on a design page, right-click a While shape and click Properties.

    The While Properties dialog box appears.

  2. In the State persistence area, click one of the following options:
    • Yes

      The messages used in each loop iteration are saved as XLANG schedule state. If the loop is part of a transaction that fails, an On Failure of Transaction or Compensation for Transaction page is called for each completed loop iteration.

    • No

      Only messages used in the latest loop iteration are saved as XLANG schedule state. If the loop is part of a transaction that fails, an On Failure of Transaction or Compensation for Transaction page is called only once.

Related Topics

Add a rule to a while loop

Create Rules

Delete a rule from a while loop

Designing Rules

Edit a rule in a while loop


Create Rules

The following procedures are covered in this section:

  • Create a rule

  • Use the expression assistant

  • Add constants to a rule

  • Delete unused rules

Related Topics

Designing Rules

Set Decision Conditions

Set While Loop Conditions


Create a rule

You can create rules to evaluate conditions within your business process. Rules are used within decisions and while loops in an XLANG schedule. When you add a rule to a Decision or While shape, the Rule Properties dialog box appears.

  1. In the Rule Properties dialog box, in the Rule name box, type a name for the rule.

    This field is required.

  2. In the Rule description box, you can type a detailed description of the rule.

    This field is optional.

  3. Place the cursor in the Script expression box to enable the expression assistant.

    You can type the script expression that you want to use, or you can use the expression assistant. For more information about using the expression assistant and creating script expressions, see Use the expression assistant.

Important

  • Because XML is case sensitive, script expressions must use the same case as messages and their fields.

  • You must place the cursor in the Script expression box to enable the expression assistant.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.
  • You cannot name any of the following shapes: Abort, Begin, Decision, End, Fork, Join, and While.

  • The length of the longest rule name determines the width of the Decision or While shape in which the rule is used.

  • You can add script expressions at any point in the Script expression box by placing the cursor at the location where you want to add the expression.

  • You cannot create script expressions until you have created the port implementations and the message communications between actions and ports.

  • Before you compile the XLANG schedule drawing into an XLANG schedule, you must complete script expressions for all rules in the schedule.

Related Topics

Add constants to a rule

Designing Rules

Set Decision Conditions

Set While Loop Conditions

Use the expression assistant


Use the expression assistant

  1. In the Rule Properties dialog box, in the Expression assistant area, click a message in the Message list.

  2. In the Expression Assistant area, click a field in the Field list.

  3. Click Insert.

  4. In the Script expression box, complete the expression.

    The expression assistant adds only the message and field that you select. To evaluate the script expression, you must provide the condition for the rule. For example:

    PORequest.Total < 500

    You can also combine expressions for more complex conditions. For example:

    PORequest.Total < 500 AND PORequest.Quantity < 20

Important

  • Because XML is case sensitive, script expressions must use the same case as messages and their fields.

  • You must place the cursor in the Script expression box to enable the expression assistant.

  • The fields that are available in the Field list are based upon the message that you choose in the Message list. Only fields contained within that message can be used.

Notes

  • The Message list contains a list of all messages and constants available on the Data page.

  • Rules can use the system fields that are provided on the Data page. When used within a rule, a system field is always surrounded by brackets. For example:

    Message1.[__Exists__]

    For more information about system fields, see Data Handling.

  • You can use Microsoft® Visual Basic® functions such as Date and Time within rules.

  • You can use all Visual Basic Scripting Edition (VBScript) expression comparison operators within rules.

  • You can add script expressions at any point in the Script expression box by placing the cursor at the location where you want to add the expression.

  • Before you compile the XLANG schedule drawing into an XLANG schedule, you must complete script expressions for all rules in the schedule.

Related Topics

Add constants to a rule

Create a rule

Designing Rules

Set Decision Conditions

Set While Loop Conditions


Add constants to a rule

You can add constants to script expressions in a rule. To use constants, you must first make constants available.

  1. On the Data page, add constants to the Constants list if no constants are already available.

    For more information about using constants and adding them to the Constants list, see Use Constants.

  2. In the Rule Properties dialog box, in the Message list, click Constants.

  3. In the Field list, click the constant that you want to use and click Insert.

Note

  • All constants in the Constants list on the Data page are available and can be used in a rule.

Related Topics

Create a rule

Designing Rules

Set Decision Conditions

Set While Loop Conditions

Use the expression assistant


Delete unused rules

  • On the Tools menu, click Delete Unused Rules.

Notes

  • This procedure deletes any rules that are not used in a decision or a while loop in the XLANG schedule drawing.

  • Only rules not currently used within any While or Decision shape are removed from the XLANG schedule drawing. Any rules that are used in a While or Decision shape are not deleted, even if these shapes are not currently connected to any other shapes.

Related Topics

Add constants to a rule

Create a rule

Use the expression assistant


Set Concurrency Properties

The following procedures are covered in this section:

  • Create concurrent flows

  • Set the Join Type property

  • Join concurrent flows

  • End a concurrent flow

Important

  • For more information about concurrent processes, it is highly recommended that you read Designing Concurrency.


Create concurrent flows

  1. In BizTalk Orchestration Designer, on a design page, click a Fork shape.

  2. Connect the bottom control handle ( Control handle) of the Fork shape to the top connection point ( Connection point) of a subsequent shape in the flow of the business process.

  3. Repeat steps 1 and 2 to create additional concurrent flows.

Important

  • For more information about concurrent processes, it is highly recommended that you read Designing Concurrency.

Notes

  • Only one flow can enter a Fork shape from the top connection point.

  • As many as 64 flows can exit a Fork shape to run concurrent processes.

  • You must click the Fork shape to select it and activate the control handle each time you want to draw an additional flow.

    –Or–

    If you want to create several concurrent flows, you can use the Connector Tool to add the flows quickly. For more information about the Connector Tool, see Use the Connector Tool.

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Connect two shapes

End a concurrent flow

Join concurrent flows

Select a shape

Set the Join Type property

Use the Connector Tool


Set the Join Type property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Join shape and click Properties.

    The Join Properties dialog box appears.

  2. In the Join type list, click one of the following options:
    • AND

    • OR

Important

  • For more information about concurrent processes, it is highly recommended that you read Designing Concurrency.

Note

  • If you select the OR join option, all flows that enter the join can have only one action associated with the flow.

Related Topics

Create concurrent flows

End a concurrent flow

Join concurrent flows


Join concurrent flows

  1. In BizTalk Orchestration Designer, on a design page, click a shape in the business process that is running a concurrent process.

  2. Connect the bottom control handle ( Control handle) of the shape to the top connection point ( Connection point) of the Join shape.

  3. Repeat steps 1 and 2 for all concurrent flows that rejoin this particular join.

Important

  • For more information about concurrent processes, it is highly recommended that you read Designing Concurrency.

Notes

  • If you select the OR join option, all flows that enter the join can have only one action associated with the flow.

  • As many as 64 flows can enter a Join shape at the top connection point.

  • Only one flow can leave a Join shape from the bottom connection point.

  • If you want to join several concurrent flows, you can use the Connector Tool to join the flows quickly. For more information about the Connector Tool, see Use the Connector Tool.

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Connect two shapes

Create concurrent flows

End a concurrent flow

Select a shape

Set the Join Type property

Use the Connector Tool


End a concurrent flow

  1. In BizTalk Orchestration Designer, on a design page, click a shape in the business process that is running a concurrent process.

  2. Connect the bottom control handle ( Control handle) of the shape to the top connection point ( Connection point) of the End shape.

    This concurrent process ends. It does not rejoin other flows in the XLANG schedule.

Important

  • For more information about concurrent processes, it is highly recommended that you read Designing Concurrency.

Note

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Connect two shapes

Create concurrent flows

Join concurrent flows

Select a shape

Set the Join Type property

Use the Connector Tool


Set Transaction Properties

The following topics are covered in this section:

  • Set Transaction Properties for an XLANG Schedule

  • Set Individual Transaction Properties

  • Describe Component and Message Queuing Transaction Support

Related Topic

Designing Transactions


Set Transaction Properties for an XLANG Schedule

The following procedures are covered in this section:

  • Set the transaction model

  • Set the transaction activation property

Related Topic

Designing Transactions


Set the transaction model

  1. In BizTalk Orchestration Designer, on a design page, right-click the Begin shape and click Properties.

    The Begin Properties dialog box appears.

  2. In the Transaction model list, click one of the following options:
    • Include Transactions within the XLANG Schedule

      This option enables an XLANG schedule to use transactions.

    • Treat the XLANG Schedule as a COM+ Component

      This option disables transaction support for an XLANG schedule. A COM component can then activate the XLANG schedule within the context of a COM+ transaction.

Notes

  • If you set the Transaction model property to Treat the XLANG Schedule as a COM+ Component, the Transaction activation list is enabled.

  • If you set the Transaction model property to Treat the XLANG Schedule as a COM+ Component, do not add transactions to the XLANG schedule drawing. The XLANG schedule drawing will not compile, and you will receive an error message.

  • The XLANG identity property is a unique ID that is used to distinguish version instances of an XLANG schedule drawing. This property is read-only and cannot be changed. Every time you update an XLANG schedule drawing, this identity is also updated.

    You can use the XLANG identity property to match versions of an XLANG schedule drawing (.skv) with the associated compiled XLANG schedule (.skx).

  • The Begin shape is available on the Business Process, Compensation for Transaction, and On Failure of Transaction pages. The Begin shape is not available on the Data page.

Related Topics

Describe Component and Message Queuing Transaction Support

Designing Transactions

Set the transaction activation property


Set the transaction activation property

  1. In BizTalk Orchestration Designer, on a design page, right-click the Begin shape and click Properties.

    The Begin Properties dialog box appears.

  2. In the Transaction model list, click Treat the XLANG Schedule as a COM+ Component.

    When you enable this option, Component Services treats the XLANG schedule as a COM+ component. This option disables transaction support for an XLANG schedule. A COM component can then activate the XLANG schedule within the context of a COM+ transaction.

  3. In the Transaction activation list, click one of the following options:
    • Not Supported

      The XLANG schedule ignores the transaction on its creator's COM+ object context, if present. None of the schedule's actions are performed within the scope of a transaction.

    • Supported

      The XLANG schedule participates in a COM+ transaction if a transaction is present on its creator's COM+ object context.

    • Required

      The XLANG schedule must run within the scope of a transaction. If a transaction is not present on the schedule creator's COM+ object context, a transaction is automatically created and used by the XLANG Scheduler Engine.

    • Requires New

      The XLANG schedule must run within the scope of a new transaction. The XLANG Scheduler Engine automatically creates a new transaction for the schedule that is distinct from any transaction that may have been present on the creator's COM+ object context.

Notes

  • The XLANG identity property is a unique ID that is used to distinguish version instances of an XLANG schedule drawing. This property is read-only and cannot be changed. Every time you update an XLANG schedule drawing, this identity is also updated.

    You can use the XLANG identity property to match versions of an XLANG schedule drawing (.skv) with the associated compiled XLANG schedule (.skx).

  • The Begin shape is available on the Business Process, Compensation for Transaction, and On Failure of Transaction pages. The Begin shape is not available on the Data page.

Related Topics

Describe Component and Message Queuing Transaction Support

Designing Transactions

Set the transaction model


Set Individual Transaction Properties

The following procedures are covered in this section:

  • Group actions and flows within a transaction

  • Design nested transactions

  • Create flows that enter and leave transactions

  • Name a transaction

  • Set the transaction Type property

  • Set the Timeout property

  • Set the Retry count property

  • Set the Backoff time property

  • Set the Isolation level property

  • Set the Persist Schedule State property

Related Topic

Designing Transactions


Group actions and flows within a transaction

  1. In BizTalk Orchestration Designer, on a design page, drag a Transaction shape from the Flowchart stencil to the left side of the Separator bar.

  2. Resize the Transaction shape to surround the shapes you want enclosed within the transaction.

Notes

  • Any shape or flow within the boundaries of a transaction is considered part of that transaction.

  • To select a shape that is within a transaction, click the shape.

  • If you delete a transaction that contains shapes within its boundaries, all contained shapes are also deleted.

  • Transaction types are denoted by the following colors:
    • Blue. This color denotes timed transactions.

    • Beige. This color denotes long-running transactions.

    • Gray. This color denotes short-lived, DTC-style transactions.
  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Create flows that enter and leave transactions

Designing Transactions

Design nested transactions

Name a transaction


Design nested transactions

  1. In BizTalk Orchestration Designer, on a design page, drag a Transaction shape from the Flowchart stencil and place it within the boundaries of a current transaction.

  2. Resize the Transaction shape to surround the shapes you want enclosed within the transaction.

Important

  • When you create a nested transaction, certain properties in the outer transaction are disabled:
    • The Short-lived, DTC-style transaction type is unavailable.

    • All options in the Transaction options area are unavailable.

    • The Timeout property is still active, but it cannot be changed after you create a nested transaction unless you change the transaction type to Timed transaction.

Notes

  • Any shape or flow within the boundaries of a transaction is considered part of that transaction.

  • To select a shape that is within a transaction, click the shape.

  • If you delete a transaction that contains shapes within its boundaries, all contained shapes are also deleted.

  • Transaction types are denoted by the following colors:
    • Blue. This color denotes timed transactions.

    • Beige. This color denotes long-running transactions.

    • Gray. This color denotes short-lived, DTC-style transactions.
  • Flowchart shapes that are not fully contained within an inner transaction are considered part of the outer transaction.

  • Flowchart shapes contained within an outer transaction might be partially hidden from view if an inner transaction partially overlaps them and they are not fully contained within the inner transaction. Select these shapes and reposition them so that they do not overlap.

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Create flows that enter and leave transactions

Designing Transactions

Group actions and flows within a transaction

Name a transaction


Create flows that enter and leave transactions

  1. In BizTalk Orchestration Designer, on a design page, click a shape that precedes a transaction in the flow of the business process.

  2. Connect the bottom control handle ( Control handle) of the shape to the top connection point ( Connection point) of the Transaction shape.

  3. Click the Transaction shape to select it.

  4. Connect the top control handle of the Transaction shape to the top connection point of the first shape within the transaction that represents the beginning of the transactional flow.

  5. From that shape connect the flow to the next shape within the transaction.

  6. Connect all the flows within the transaction, and connect any actions to the ports for which you want to create a communication flow.

  7. From the bottom control handle of the last shape within the transaction, connect the flow to the bottom connection point of the Transaction shape.

  8. Click the Transaction shape to select it.

  9. Connect the bottom control handle of the Transaction shape to the top connection point of the next shape in the flow of the business process that is outside the transaction.

Notes

  • To select a shape that is within a transaction, click the shape.

  • You can add Flowchart shapes to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Flowchart shapes are not available on the Data page.

Related Topics

Add, Delete, and Connect Shapes

Connect two shapes

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Use the Connector Tool


Name a transaction

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Name box, type a name for the transaction.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.
  • Transaction names in single-byte character sets must be less than or equal to 16 characters in length. Transaction names in double-byte character sets must be less than or equal to 8 characters in length.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Set the Persist Schedule State property

Set the Backoff time property

Set the Isolation level property

Set the Retry count property

Set the Timeout property

Set the transaction Type property


Set the transaction Type property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Type area, click one of the following options:
    • Timed transaction

    • Short-lived, DTC-style

    • Long-running

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Persist Schedule State property

Set the Backoff time property

Set the Isolation level property

Set the Retry count property

Set the Timeout property


Set the Timeout property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Transaction options area, in the Timeout box, enter a time in seconds.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Persist Schedule State property

Set the Backoff time property

Set the Isolation level property

Set the Retry count property

Set the transaction Type property


Set the Retry count property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Transaction options area, in the Retry count box, enter the number of times a transaction can be retried before it is considered to have failed.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Persist Schedule State property

Set the Backoff time property

Set the Isolation level property

Set the Timeout property

Set the transaction Type property


Set the Backoff time property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Transaction options area, in the Backoff time box, enter a time in seconds.

Note

  • The Backoff time property determines the interval between each attempt to retry the transaction. This option is available only for short-lived, DTC-style transactions. The backoff time is used with the retry count value to determine how long to wait before the next transaction retry. The backoff value is exponential. A backoff value of 2 seconds results in intervals of 2, 4, 8, 16 seconds, and so on between each retry. The formula is BR (B raised to the power of R), where B=backoff time and R=current retry count.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Persist Schedule State property

Set the Isolation level property

Set the Retry count property

Set the Timeout property

Set the transaction Type property


Set the Isolation level property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Transaction options area, in the Isolation level list, click one of the following options:
    • Serializable

    • Read Uncommitted

    • Read Committed

    • Repeatable Read

Note

  • This property can be set only for short-lived, DTC-style transactions.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Persist Schedule State property

Set the Backoff time property

Set the Retry count property

Set the Timeout property

Set the transaction Type property


Set the Persist Schedule State property

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Transaction options area, select or clear the Persist Schedule State check box.

Note

  • This property cannot be edited for short-lived, DTC-style transactions; they are always persisted.

Related Topics

Designing Transactions

Design nested transactions

Group actions and flows within a transaction

Name a transaction

Set the Isolation level property

Set the Backoff time property

Set the Retry count property

Set the Timeout property

Set the transaction Type property


Describe Component and Message Queuing Transaction Support

The following procedures are covered in this section:

  • Describe the level of transaction support in a COM component

  • Describe the level of transaction support in a Windows Script Component

  • Describe the transaction support provided by a message queue

Related Topics

Designing Transactions

Set the transaction activation property

Set the transaction model


Describe the level of transaction support in a COM component

Transaction support for COM components is set within the COM Component Binding Wizard.

  1. Open the COM Component Binding Wizard.

    For more information about this wizard, see Implement a port by using a COM component.

  2. Follow the instructions in the wizard until you reach the Advanced Port Properties page.

  3. On the Advanced Port Properties page, in the Transaction support area, click one of the following options:
    • Disabled

      Transaction support for the COM+ component used by this port implementation is disabled.

    • Not supported

      The COM+ component used by this port implementation does not support transactions.

    • Supported

      The COM+ component used by this port implementation inherits an existing transaction.

    • Required

      The COM+ component used by this port implementation can inherit an existing transaction, or use a new transaction.

    • Requires new

      The COM+ component used by this port implementation requires that a new transaction be used.

Related Topics

Add a bound port to an XLANG schedule drawing

Designing Transactions

Implement a port by using a COM component

Modify port implementation properties

Set the transaction activation property

Set the transaction model


Describe the level of transaction support in a Windows Script Component

Transaction support for Windows Script Components is set within the Script Component Binding Wizard.

  1. Open the Script Component Binding Wizard.

    For more information about this wizard, see Implement a port by using a Windows Script Component.

  2. Follow the instructions in the wizard until you reach the Advanced Port Properties page.

  3. On the Advanced Port Properties page, in the Transaction support area, click one of the following options:
    • Disabled

      Transaction support for the COM+ component used by this port implementation is disabled.

    • Not supported

      The COM+ component used by this port implementation does not support transactions.

    • Supported

      The COM+ component used by this port implementation inherits an existing transaction.

    • Required

      The COM+ component used by this port implementation can inherit an existing transaction, or use a new transaction.

    • Requires new

      The COM+ component used by this port implementation requires that a new transaction be used.

Related Topics

Add a bound port to an XLANG schedule drawing

Designing Transactions

Implement a port by using a Windows Script Component

Modify port implementation properties

Set the transaction activation property

Set the transaction model


Describe the transaction support provided by a message queue

Transaction support for message queues is set within the Message Queuing Binding Wizard.

  1. Open the Message Queuing Binding Wizard.

    For more information about this wizard, see Implement a port by using Message Queuing.

  2. Follow the instructions in the wizard until you reach the Advanced Port Properties page.

  3. On the Advanced Port Properties page, in the Transaction support area, select or clear the Transactions are required with this queue check box.

Related Topics

Add a bound port to an XLANG schedule drawing

Designing Transactions

Implement a port by using Message Queuing

Modify port implementation properties

Set the transaction activation property

Set the transaction model


Set Error Handling Properties

The following procedures are covered in this section:

  • Abort a process flow

  • Enable Transaction Error Handling

  • Enable Component Error Handling

Related Topic

Handling Exceptions


Abort a process flow

  1. In BizTalk Orchestration Designer, on the Flowchart stencil, click the Abort shape and drag it to the design page.

  2. Connect the process flow from a logical branch that exits a Decision shape to the connection point ( Connection point) of the Abort shape.

Important

  • Abort shapes are used to abort a business process in a logical branch. They are used along with decisions.

    The use of the Abort shape depends upon the needs of your business process. The rules that are contained within a decision are evaluated until a rule evaluates to TRUE. If a rule evaluates to TRUE, the process flow continues to the next action. If no rules evaluate to TRUE, you might choose to abort the process flow.

    The following illustration shows an example of a decision condition where, if the rule evaluates to TRUE, the process flow continues to Action 3. If the rule does not evaluate to TRUE, the process flow is aborted.

    The use of an Abort shape in a logical branch

Related Topics

Enable Component Error Handling

Enable Transaction Error Handling

Handling Exceptions

Logical Branching


Enable Transaction Error Handling

The following procedures are covered in this section:

  • Enable On Failure error handling

  • Enable Compensation error handling

Related Topics

Abort a process flow

Handling Exceptions


Enable On Failure error handling

  1. In BizTalk Orchestration Designer, on a design page, right-click a Transaction shape and click Properties.

    The Transaction Properties dialog box appears.

  2. In the On failure area, click Add Code.

  3. In the On failure area, select the Enabled check box.

Notes

  • Clicking the Add Code button creates the On Failure of Transaction page that is associated with this transaction. The parameter Transaction in the name of the page is replaced with the name of the transaction with which the error-handling process is associated.

  • Selecting the Enabled check box enables the XLANG schedule to run the On Failure code for this transaction. If you do not select this check box, you can still design On Failure processes, but they do not run when the XLANG schedule is run.

Related Topics

Design nested transactions

Group actions and flows within a transaction

Handling Exceptions


Enable Compensation error handling

  1. In BizTalk Orchestration Designer, on a design page, right-click an inner Transaction shape in a nested transaction group and click Properties.

    The Transaction Properties dialog box appears.

  2. In the Compensation area, click Add Code.

  3. In the Compensation area, select the Enabled check box.

Notes

  • Clicking the Add Code button creates the On Failure of Transaction or Compensation for Transaction page that is associated with this transaction.

  • Selecting the Enabled check box enables the XLANG schedule to run the On Failure code or Compensation code for this transaction. If you do not select this check box, you can still design an On Failure or a Compensation process, but it does not run when the XLANG schedule is run.

  • The parameter Transaction in the name of the page is replaced with the name of the transaction with which the error-handling process is associated.

  • Transaction types are denoted by the following colors:
    • Blue. This color denotes timed transactions.

    • Beige. This color denotes long-running transactions.

    • Gray. This color denotes short-lived, DTC-style transactions.

Related Topics

Design nested transactions

Group actions and flows within a transaction

Handling Exceptions


Enable Component Error Handling

The following procedures are covered in this section:

  • Abort a transaction if a COM component returns a failure

  • Abort a transaction if a Windows Script Component returns a failure

Related Topics

Abort a process flow

Handling Exceptions


Abort a transaction if a COM component returns a failure

Transaction support for COM components is set within the COM Component Binding Wizard.

  1. Open the COM Component Binding Wizard.

    For more information about this wizard, see Implement a port by using a COM component.

  2. Follow the instructions in the wizard until you reach the Advanced Port Properties page.

  3. On the Advanced Port Properties page, in the Error handling area, select the Abort the transaction if the method returns a failure HRESULT check box.

Important

  • This option determines whether short-lived, DTC-style transactions in which the component is used should be aborted when method calls to the component return a failure HRESULT.

    This option can be set only if the communication action that uses this port is within the process flow of a transaction.

Related Topics

Abort a transaction if a Windows Script Component returns a failure

Add a bound port to an XLANG schedule drawing

Handling Exceptions

Implement a port by using a COM component

Modify port implementation properties

Set the transaction activation property

Set the transaction model


Abort a transaction if a Windows Script Component returns a failure

Transaction support for Windows Script Components is set within the Script Component Binding Wizard.

  1. Open the Script Component Binding Wizard.

    For more information about this wizard, see Implement a port by using a Windows Script Component.

  2. Follow the instructions in the wizard until you reach the Advanced Port Properties page.

  3. On the Advanced Port Properties page, in the Error handling area, select the Abort the transaction if the method returns a failure HRESULT check box.

Important

  • This option determines whether transactions in which the component is used should be aborted when method calls to the component return a failure HRESULT.

    This option can be set only if the communication action that uses this port is within the process flow of a transaction.

Related Topics

Abort a transaction if a COM component returns a failure

Add a bound port to an XLANG schedule drawing

Handling Exceptions

Implement a port by using a Windows Script Component

Modify port implementation properties

Set the transaction activation property

Set the transaction model


Implement Ports

BizTalk Orchestration Designer provides four Implementation shapes that represent technologies that can be used to implement port communications. The following table describes these shapes.

Shape name | Description
COM Component | The COM Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received. Drag this shape to the right side of the Separator bar to open the COM Component Binding Wizard.
Script Component | The Script Component shape represents a technology that can be used to implement a port by using a method call for each message that is sent or received. Drag this shape to the right side of the Separator bar to open the Script Component Binding Wizard.
Message Queuing | The Message Queuing shape represents a technology that can be used to implement a port. Message Queuing Services are used to send or receive messages. Drag this shape to the right side of the Separator bar to open the Message Queuing Binding Wizard.
BizTalk Messaging | The BizTalk Messaging shape represents a technology that can be used to implement a port. BizTalk Messaging Services are used to send or receive messages. Either a BizTalk Server messaging port or a channel can be used to implement a port. Drag this shape to the right side of the Separator bar to open the BizTalk Messaging Binding Wizard.

The following procedures are covered in this section:

  • Add an unbound port to an XLANG schedule drawing

  • Add a bound port to an XLANG schedule drawing

  • Implement a port by using a COM component

  • Implement a port by using a Windows Script Component

  • Implement a port by using Message Queuing

  • Implement a port by using BizTalk Messaging

  • Modify port implementation properties

Related Topics

Communication Shapes

Flowchart Shapes

Implementation Shapes

Implementing Business Processes

Match a specific message with a specific port

Send or Receive Messages

Understanding Port Implementations

Using the Method Communication Wizard

Using the XML Communication Wizard


Add an unbound port to an XLANG schedule drawing

  • In BizTalk Orchestration Designer, on a design page, right-click the Separator bar and click Add New Port.

Notes

  • You can add a port to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Ports are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • An unbound port can be implemented by using either Message Queuing or BizTalk Messaging. When you add one of those implementations to the page, the implementation wizard provides the option to select any available unbound ports.

Related Topics

Implement a port by using a COM component

Implement a port by using a Windows Script Component

Implement a port by using BizTalk Messaging

Implement a port by using Message Queuing

Match a specific message with a specific port

Modify port implementation properties

Send or Receive Messages


Add a bound port to an XLANG schedule drawing

  • In BizTalk Orchestration Designer, on a design page, drag an Implementation shape from the Implementation stencil to the right side of the Separator bar and follow the steps in the wizard for that implementation.

Notes

  • You can add a port to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Ports are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

Related Topics

Implement a port by using a COM component

Implement a port by using a Windows Script Component

Implement a port by using BizTalk Messaging

Implement a port by using Message Queuing

Match a specific message with a specific port

Modify port implementation properties

Send or Receive Messages


Implement a port by using a COM component

  1. In BizTalk Orchestration Designer, on a design page, drag the COM Component shape from the Implementation stencil to the right side of the Separator bar.

    The COM Component Binding Wizard opens.

  2. On the Welcome to the COM Component Binding Wizard page, type a name for the port that you want to create and click Next.

    BizTalk Orchestration Designer provides a default port name with a number appended to it for each new port implementation that is added. You can change this name.

  3. On the Static or Dynamic Communication page, click one of the following options:
    • Static

      The XLANG Scheduler Engine instantiates this component.

      If you click the Static option, the component is automatically destroyed when the XLANG schedule instance ends.

      Click Next. Continue to step 4 in this procedure.

    • Dynamic

      If you select this option, another application instantiates the component. A moniker or a pointer to the object instance must be sent back to the XLANG schedule as a field in a message. On the Data page, a connection must be drawn between that message field and the port reference for the port that uses this implementation. For more information about sending a message to a specific port, see Match a specific message with a specific port.

      Click Next. Continue to step 5 in this procedure.

    • No instantiation

      Select this option only to receive data. This option specifies that data is passed into an XLANG schedule by using a method; however, none of the code behind the method call is executed. For more information, see Data Handling.

      Click Next. Continue to step 5 in this procedure.

    For more information about static and dynamic communications, see the following topics:

    • Static and Dynamic Ports

    • Instance Management

    • Using the Script Component Shape
  4. On the Class Information page, click one of the following options:
    • From a registered component

      A tree control displays all components registered on your computer. Expand the folder for the class that you want and click the class.

      Click Next.

    • From a moniker

      Type the name of a standard COM moniker to specify the location of the COM component that you want to instantiate. If you use this option, the COM component cannot be used with communications that take place within a transaction in the XLANG schedule.

      Click Next.

  5. On the Interface Information page, click the interface that you want to use and click Next.

    Notes

    • If the COM component has only one interface, this page is skipped.

    • If the COM component was created in Microsoft Visual Basic, there is one interface of the same name as each class contained within the component. Each interface name is prefaced with an underscore (_).
  6. On the Method Information page, select the methods that you want to use and click Next.

    Notes

    • If the COM component has only one method, this page is skipped.

    • You must select at least one method.

    • You can select several methods, or all of them. The Check All and Uncheck All buttons enable you to either select or deselect all the methods.
  7. On the Advanced Port Properties page, in the Security area, click one of the following options:
    • Not required

      No attempt is made to confirm the identity of the sender.

    • Optional

      The XLANG Scheduler Engine requests the identity of the sender. The XLANG schedule continues to run whether or not the identity is available.

    • Required

      The XLANG Scheduler Engine requests the identity of the sender. The sender identity is required, and the XLANG schedule ignores the message if the identity is not available.

    Note

    • If the XLANG schedule rejects an incoming method call when the identity is required but is unavailable, the error code E_ACCESSDENIED is returned to the caller.
  8. On the Advanced Port Properties page, in the Transaction support area, click one of the following options:
    • Disabled

      Transaction support for the COM+ component used by this port implementation is disabled.

    • Not supported

      The COM+ component used by this port implementation does not support transactions.

    • Supported

      The COM+ component used by this port implementation inherits an existing transaction.

    • Required

      The COM+ component used by this port implementation can inherit an existing transaction or use a new transaction.

    • Requires new

      The COM+ component used by this port implementation requires that a new transaction be used.

  9. On the Advanced Port Properties page, in the State management area, click one of the following options:
    • Holds no state

      The component used by this port implementation holds no state across method calls.

    • Holds state, but doesn't support persistence

      The component used by this port implementation holds state during the lifetime of the component, but the component cannot be persisted.

    • Holds state, and does support persistence

      The component used by this port implementation holds state that can be saved by using either the IPersistStream or IPersistStreamInit interface. The use of either IPersistStream or IPersistStreamInit allows the state of the component to be saved for later instantiations, and the component is recreated using the saved state.

  10. On the Advanced Port Properties page, in the Error Handling area, select or clear the Abort the transaction if the method returns a failure HRESULT check box.

    Important

    • This option determines whether transactions in which the component is used should be aborted when method calls to the component return a failure HRESULT.

      This option can be set only if the communication action that uses this port is within the process flow of a transaction.

  11. Click Finish.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • You can add port implementations to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Port implementations are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • A new port is always created for use with a COM component implementation.

  • If you are editing an existing port implementation, on the first page of the implementation wizard, the Rename current port option enables you to rename the port.

Related Topics

Implement a port by using a Windows Script Component

Implement a port by using BizTalk Messaging

Implement a port by using Message Queuing

Implementation Shapes

Implementing Business Processes

Match a specific message with a specific port

Modify port implementation properties

Understanding Port Implementations

Using the COM Component Shape

Using the Method Communication Wizard


Implement a port by using a Windows Script Component

  1. In BizTalk Orchestration Designer, on a design page, drag the Script Component shape from the Implementation stencil to the right side of the Separator bar.

    The Script Component Binding Wizard opens.

  2. On the Welcome to the Script Component Binding Wizard page, type a name for the port that you want to create and click Next.

    BizTalk Orchestration Designer provides a default port name with a number appended to it for each new port implementation that is added. You can change this name.

  3. On the Static or Dynamic Communication page, click one of the following options and then click Next:
    • Static

      The XLANG Scheduler Engine instantiates this component.

      If you click the Static option, the component is automatically destroyed when the XLANG schedule instance ends.

    • Dynamic

      If you select this option, another application instantiates the component. A moniker or a pointer to the object instance must be sent back to the XLANG schedule as a field in a message. On the Data page, a connection must be drawn between that message field and the port reference for the port that uses this implementation. For more information about sending a message to a specific port, see Match a specific message with a specific port.

    • No instantiation

      Select this option only to receive data. This option indicates that data is passed into the XLANG schedule by using a method; however, none of the code behind the method call is executed.

    For more information about static and dynamic communications, see the following topics:

    • Static and Dynamic Ports

    • Instance Management

    • Using the Script Component Shape
  4. On the Specify the Script File page, click Browse.

    The Select Script File dialog box appears.

  5. Browse to the location of the .wsc file that you want to use, click the file, and then click Open.

  6. Click Next and continue with one of the following options:
    • If you selected Static in step 3, continue to step 7 in this procedure.

    • If you selected Dynamic or No instantiation in step 3, continue to step 8 in this procedure.
  7. On the Component Instantiation Information page, click one of the following and then click Next:
    • Use a moniker of the script file

      The path and file name of the script file is automatically provided as the moniker.

    • Use the Prog ID "Prog ID"

      The Prog ID is automatically provided, and is extracted from the XML in the Windows Script Component file. This is recommended because the path to the script file is not hard-coded.

  8. On the Method Information page, select the methods that you want to use and click Next.

    Notes

    • If the Windows Script Component has only one method, this page is skipped.

    • You must select at least one method.

    • You can select several methods, or all of them. The Check All and Uncheck All buttons enable you to either select or deselect all the methods.
  9. On the Advanced Port Properties page, in the Security area, click one of the following options:
    • Not required

      No attempt is made to confirm the identity of the sender.

    • Optional

      The XLANG Scheduler Engine requests the identity of the sender. The XLANG schedule continues to run whether or not the identity is available.

    • Required

      The XLANG Scheduler Engine requests the identity of the sender. The sender identity is required, and the XLANG schedule ignores the message if the identity is not available.

    Note

    • If the XLANG schedule rejects an incoming method call when the identity is required but is unavailable, the error code E_ACCESSDENIED is returned to the caller.
  10. On the Advanced Port Properties page, in the Transaction support area, click one of the following options:
    • Disabled

      Transaction support for the COM+ component used by this port implementation is disabled.

    • Not supported

      The COM+ component used by this port implementation does not support transactions.

    • Supported

      The COM+ component used by this port implementation inherits an existing transaction.

    • Required

      The COM+ component used by this port implementation can inherit an existing transaction or use a new transaction.

    • Requires new

      The COM+ component used by this port implementation requires that a new transaction be used.

  11. On the Advanced Port Properties page, in the Error Handling area, select or clear the Abort the transaction if the method returns a failure HRESULT check box.

    Important

    • This option determines whether transactions in which the component is used should be aborted when method calls to the component return a failure HRESULT.

      This option can be set only if the communication action that uses this port is within the process flow of a transaction.

  12. Click Finish.

Important

  • When you use Windows Script Components, they must adhere to the following rules:
    • Argument declarations must be by reference, not by value.

    • Microsoft Visual Basic Scripting subroutines are not supported. Only functions are supported.

    • Multiple components cannot be used within a single .wsc file.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • You can add port implementations to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Port implementations are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • A new port is always created for use with a Windows Script Component implementation.

  • If you are editing an existing port implementation, on the first page of the implementation wizard, the Rename current port option allows you to rename the port.

  • Windows Script Component files use the file extension .wsc. For more information about Windows Script Components, go to the Windows Scripting Technologies Web site (msdn.microsoft.com/scripting/default.htm) and browse to the Windows Script Components page.

  • Windows Script Components that have been run by the XLANG Scheduler Engine cannot be modified until both the XLANG Scheduler Engine and the Windows Script Host are shut down.

Related Topics

Implement a port by using a COM component

Implement a port by using BizTalk Messaging

Implement a port by using Message Queuing

Implementation Shapes

Implementing Business Processes

Match a specific message with a specific port

Modify port implementation properties

Understanding Port Implementations

Using the Script Component Shape

Using the Method Communication Wizard


Implement a port by using Message Queuing

  1. In BizTalk Orchestration Designer, on a design page, drag the Message Queuing shape from the Implementation stencil to the right side of the Separator bar.

    The Message Queuing Binding Wizard opens.

  2. On the Welcome to the Message Queuing Binding Wizard page, click one of the following options and click Next:
    • Create a new port

      BizTalk Orchestration Designer provides a default port name with a number appended to it for each new port implementation that is added. You can change this name.

    • Existing unbound port

      In the Existing unbound port list, click the port that you want to use.

      Only names for unbound ports appear in the Existing unbound port list. An unbound port has no defined implementation.

  3. On the Static or Dynamic Queue Information page, click one of the following options:
    • Static queue

      A static queue is a known, preexisting queue. This queue must be known at design time.

      Click Next. Continue to step 4 in this procedure.

    • Dynamic queue

      If you select this option, on the Data page you must create a link from a message field to the port reference for this port.

      The name of the message queue must be provided by another message prior to the communication action that occurs by using this port implementation. For more information about matching a specific message with a specific port, see Match a specific message with a specific port.

      Click Next. Continue to step 5 in this procedure.

      For more information about static and dynamic queues, see Static and Dynamic Ports.

  4. On the Queue Information page, click one of the following options and click Next:
    • Create a new queue for every instance

      You must assign the queue a prefix (for example: ".\Private$\PrivateQueuePrefix" or ".\PublicQueuePrefix"). A unique ID is appended to the prefix for each new queue that is created.

      A default queue prefix is provided for you. You can change this default.

      If you want to enable someone to reply to this port, a reference to this port must be sent in a message. To do this, select Create a new queue for every instance and enter a root queue name. At run time, the XLANG Scheduler Engine creates a new queue with this root name for every instance, and an instance GUID is appended to the root name for each queue created. This queue is deleted when the instance ends.

      If you do not plan to send out a reference to this port, there is no need for a per-instance queue. You can create a queue that will be used for all instances.

    • Use a known queue for all instances

      Enter the queue name of a known, preexisting queue (for example: ".\private$\queuename").

  5. On the Advanced Port Properties page, in the Security area, click one of the following options:
    • Not required

      No attempt is made to confirm the identity of the sender. The XLANG schedule always receives the message with a blank __Sender__ field, whether or not the message is authenticated.

    • Optional

      The XLANG Scheduler Engine sends a request for confirmation of the identity of the sender. The XLANG schedule receives the message, whether or not a message is authenticated. If the message is authenticated, the __Sender__ field contains the Message Queuing message SenderID property.

    • Required

      The XLANG Scheduler Engine sends a request for confirmation of the identity of the sender. Confirmation of the sender identity is required. If the message is authenticated, the XLANG schedule receives the message, and the __Sender__ field contains the Message Queuing message SenderID property.

      If the message is not authenticated, an application event-log entry is created, and the message is moved to a new queue that is created and named .\private$\<ApplicationName>.DeadLetter.

  6. On the Advanced Port Properties page, in the Security area, select or clear the Use a Windows Group or User Name to control the queue check box.

    If you select the check box, enter the name of the user or group that is permitted to write messages to the queue. This option is available only if you are using a static queue.

  7. On the Advanced Port Properties page, in the Transaction support area, select or clear the Transactions are required with this queue check box.

  8. Click Finish.

Notes

  • You can add port implementations to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Port implementations are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • If you are editing an existing port implementation, on the first page of the implementation wizard, the Rename current port option allows you to rename the port.

Related Topics

Implement a port by using a COM component

Implement a port by using a Windows Script Component

Implement a port by using BizTalk Messaging

Implementation Shapes

Implementing Business Processes

Match a specific message with a specific port

Modify port implementation properties

Understanding Port Implementations

Using the Message Queuing Shape

Using the XML Communication Wizard


Implement a port by using BizTalk Messaging

  1. In BizTalk Orchestration Designer, on a design page, drag the BizTalk Messaging shape from the Implementation stencil to the right side of the Separator bar.

    The BizTalk Messaging Binding Wizard opens.

  2. On the Welcome to the BizTalk Messaging Binding Wizard page, click one of the following options and click Next:
    • Create a new port

      BizTalk Orchestration Designer provides a default port name with a number appended to it for each new port implementation that is added. You can change this name.

    • Existing unbound port

      In the Existing unbound port list, click the port that you want to use.

      Only names for unbound ports appear in the Existing unbound port list. An unbound port has no defined implementation.

  3. On the Communication Direction page, click one of the following options:
    • Send

      Click Next. Continue to step 4 in this procedure.

    • Receive

      Click Next. Continue to step 5 in this procedure.

    Note

    • If you choose Receive, messages can be received by using an HTTP URL destination, or by using BizTalk Messaging Manager to configure a messaging port to instantiate an XLANG schedule, and send messages to a specific port in that schedule. For more information about receiving messages by using an HTTP URL, see Integrating BizTalk Services. For more information about using BizTalk Messaging Manager to configure a messaging port, see Set destination application properties.
  4. On the Static or Dynamic Channel Information page, click one of the following options and then click Finish:
    • Static channel

      Enter the name of a known, preexisting channel.

    • Dynamic channel

      If you select this option, you must configure the port to provide the data that BizTalk Messaging Services needs at run time to identify the correct channel to process the message.

      On the Data page, you must create a link from a message field of a previously received message to the port reference for this port. The message field must contain a destination address, which BizTalk Messaging Services uses as the destination address for an open messaging port that is associated with that channel. For more information, see Integrating BizTalk Services.

      When you establish the communication flow from an action to this port, you use the XML Communication Wizard. On the Message Type Information page, in the Message type box, you must enter the name of the inbound document definition for the channel. BizTalk Messaging Services uses this data to identify the correct channel to process the message. For more information, see Identification.

    Important

    • There must be at least one channel configured in BizTalk Messaging Services that uses the specified inbound document definition. When an action communicates with a port bound to BizTalk Messaging and the specified channel for the binding does not exist, the XLANG schedule instance will failfast with an event log entry.

    • There should be only one channel configured in BizTalk Messaging Services that uses the specified inbound document definition and is configured with XLANG schedule as its source. For more information, see Set source application properties. That channel also must be associated with an open messaging port. When an action communicates with a port bound to BizTalk Messaging and more than one channel for the binding exists, the XLANG schedule instance will failfast with an event log entry.
  5. On the XLANG Schedule Activation Information page, click one of the following options:
    • Yes

      This port cannot be used in multiple receive actions or within a single receive action within a loop.

      Click Finish.

    • No

      Click Next.

  6. On the Channel Information page, in the Channel name box, type the name of the channel that you want to use. For more information about channels, see Understanding Channels and Search for channels.

  7. On the Channel Information page, in the HTTP URL address where the BizTalk Messaging Service receives documents box, type the URL address from which BizTalk Server receives documents for this channel.

  8. Click Finish.

Important

  • If you configure a port to activate a new XLANG schedule when a message arrives, you must observe the following restrictions:
    • Only one port in a schedule can be used to activate the schedule when the message arrives.

    • Only one action can receive through this port.

    • This one action cannot be in a loop body.

    • You cannot draw a data flow connection from the port reference for this port to any other message in the schedule.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • You can add port implementations to the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Port implementations are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • If you are editing an existing port implementation, on the first page of the implementation wizard, the Rename current port option allows you to rename the port.

International Issue

  • If non-ASCII characters are included in the name of a non-activation receive channel, submitting documents with HTTP might not succeed. The channel name is passed in the query string of a URL, and non-ASCII characters are not supported in query strings.

Related Topics

Implement a port by using a COM component

Implement a port by using a Windows Script Component

Implement a port by using Message Queuing

Implementation Shapes

Implementing Business Processes

Integrating BizTalk Services

Match a specific message with a specific port

Modify port implementation properties

Search for channels

Understanding Channels

Understanding Port Implementations

Using the BizTalk Messaging Shape

Using the XML Communication Wizard


Modify port implementation properties

  1. In BizTalk Orchestration Designer, on a design page, right-click an Implementation shape that you want to modify.

  2. Click Properties.

    The wizard for that Implementation shape opens.

  3. Follow the steps in the wizard and change any properties that you want to modify.

Notes

  • You can modify port implementations on the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Port implementations are not available on the Data page.

  • You cannot add shapes to the Data page. A port reference is created automatically on the Data page each time you create a new port.

  • On the first page of the implementation wizard, the Rename current port option allows you to rename the port.

Related Topics

Implement a port by using a COM component

Implement a port by using a Windows Script Component

Implement a port by using BizTalk Messaging

Implement a port by using Message Queuing

Implementation Shapes

Implementing Business Processes


Send or Receive Messages

BizTalk Orchestration Designer provides two forms of communication by which an XLANG schedule can send or receive messages:

  • Synchronous communication. Method calls are used to send or receive synchronous message pairs.

  • Asynchronous communication. XML messages are used to send or receive asynchronous messages.

For more information, see Synchronous and Asynchronous Communication.

The following procedures are covered in this section:

  • Establish the communication flow between an action and a port

  • Send or receive synchronous messages

  • Send or receive asynchronous messages

  • Modify the communication flow between an action and a port

Related Topics

Synchronous and Asynchronous Communication

Using the Method Communication Wizard

Using the XML Communication Wizard


Establish the communication flow between an action and a port

  1. In BizTalk Orchestration Designer, on a design page, click an Action shape to select it.

  2. Drag the right control handle ( Control handle) of the Action shape to the connection point ( Connection point) of a Port shape.

    A communication wizard opens.

  3. Continue to one of the following procedures, depending on which type of communication flow you want to create:
    • If you want to create a synchronous communication flow to a port that uses a COM Component or Script Component implementation, use the Method Communication Wizard. Continue to Send or receive synchronous messages.

    • If you want to create an asynchronous communication flow to a port that uses a Message Queuing or BizTalk Messaging implementation, or if you want to create an asynchronous communication flow to an unbound port, use the XML Communication Wizard. Continue to Send or receive asynchronous messages.

Notes

  • You can also use the Connector Tool to connect shapes. For more information, see Use the Connector Tool.

  • You can establish a communication flow between an action and a port on the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Actions and ports are not available on the Data page.

  • You cannot add shapes to the Data page. New messages are created automatically on the Data page each time an action is connected to a port.


Send or receive synchronous messages

In BizTalk Orchestration Designer, after you have created a communication flow between an action and a port for a synchronous communication, the Method Communication Wizard opens. For more information about creating a communication flow, see Establish the communication flow between an action and a port.

  1. On the Welcome to the Method Communication Wizard page, click one of the following options:
    • Initiate a synchronous method call

      The XLANG Scheduler Engine initiates a synchronous method call.

      In this case, the XLANG Scheduler Engine sends a method call to a component, waits for a response from the component, and then receives a response.

      Click Next. Continue to step 3 in this procedure.

    • Wait for a synchronous method call

      The XLANG Scheduler Engine waits to receive a method call that is initiated by another application.

      In this case, the XLANG Scheduler Engine waits for another application to initiate the method call. This separate application sends a method call to a component; the XLANG Scheduler Engine waits for a response from the component and then returns a response to the application. The XLANG schedule intercepts both the method request and the method response.

      Continue to step 2 in this procedure.

  2. On the Welcome to the Method Communication Wizard page, to optimize the execution of an XLANG schedule, enter the amount of time (in seconds) that you expect the XLANG Scheduler Engine to wait before a message arrives and click Next.

    The default wait time is 0 seconds. You can change this time. Any time less than or equal to 180 seconds causes the XLANG schedule to never dehydrate. Any time greater than 180 seconds causes the XLANG schedule to dehydrate immediately. For more information about wait times and XLANG schedule dehydration, see Dehydration and Rehydration and Using the Method Communication Wizard.

  3. On the Message Information page, click one of the following options:
    • Create a new message

      The name of this message is automatically determined by the method that you select on the next page of this wizard. The data flow for a new message must be connected to other messages on the Data page.

      Click Next. Continue to step 4 in this procedure.

    • Add a reference to an existing synchronous message pair

      A reference to a previously configured message pair is added to this communication flow. These message pairs can be reused only within the same port. They cannot be used by another port implementation.

      Click Finish.

  4. On the Message Specification Information page, in the Methods list, click the method that you want to use. You can select only one method in the list.

    Selecting a method defines the messages for this communication flow. The IN and OUT parameters are automatically determined by the parameter requirements of the method that you choose. Both parameter lists contain the name and data type of the parameter.

    For more information about defining the messages used in a communication flow, see Synchronous Communication.

  5. Click Finish.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • The wait time property is not enabled unless you click Wait for a synchronous method call.

  • The only methods available for use in a synchronous communication are those that were selected for the port implementation. Methods from other port implementations cannot be used, and XML messages from asynchronous communication flows cannot be used. To change the available methods, rerun the appropriate port implementation wizard and select different methods.

  • When you create a synchronous communication, a Message is created on the Data page. The Message corresponds to the method and parameters that are used in the communication flow. The Message contains all IN parameters for the method.

    It is possible for a method to contain no parameters; however, the Message always contains required system fields. For more information about defining the messages used in a synchronous communication, see Synchronous Communication.

Related Topics

Dehydration and Rehydration

Establish the communication flow between an action and a port

Implement Ports

Send or receive asynchronous messages

Synchronous Communication

Using the Method Communication Wizard

Using the XML Communication Wizard


Send or receive asynchronous messages

  1. On the Welcome to the XML Communication Wizard page, choose one of the following options:
    • Send

      A message is sent asynchronously.

      Click Next. Continue to step 3 in this procedure.

    • Receive

      The XLANG Scheduler Engine waits until it receives a message before continuing the XLANG Schedule.

      Continue to step 2 in this procedure.

  2. On the Welcome to the XML Communication Wizard page, to optimize the execution of an XLANG schedule, enter the amount of time (in seconds) that you expect the XLANG Scheduler Engine to wait before a message arrives and click Next.

    The default wait time is 0 seconds. You can change this time. Any time less than or equal to 180 seconds causes the XLANG schedule to never dehydrate. Any time greater than 180 seconds causes the XLANG schedule to dehydrate immediately. For more information about wait times and XLANG schedule dehydration, see Dehydration and Rehydration and Using the XML Communication Wizard.

  3. On the Message Information page, click one of the following options:
    • Create a new message

      In the Message name box, type the name of the message. A default message name with a number appended to it is provided; however, you can change this name.

      The data flow for a new message must be connected to other messages on the Data page.

    • Add a reference to an existing message

      A reference to a previously configured message is added to this communication flow.

  4. Click Next and do one of the following:
    • If you clicked Send on the Welcome to the XML Communication Wizard page, continue to step 5 in this procedure.

    • If you clicked Receive on the Welcome to the XML Communication Wizard page, continue to step 8 in this procedure.
  5. On the XML Translation Information page, click one of the following options and click Next:
    • Send XML messages to the queue

    • Send messages to the queue as a string

      The XLANG Scheduler Engine must remove the standard XML wrapper from the string.

    Data flow in the XLANG Scheduler Engine is handled by using XML. The engine natively sends XML messages to message queues. The engine can also send a message as a string, from which the engine must remove its standard XML wrapper. The data flow must deliver a message in the correct specification format for this action.

    If you choose to send or receive an XML message as a string, the Message shape that is created on the Data page for this message contains a field named StringData, and you cannot add specification fields to this message.

  6. On the Message Type Information page, in the Message type box, type a label designation for the message.

    The text that you enter is used to label the message as it is sent to the queue.

  7. To continue, do one of the following:
    • If, on the XML Translation Information page, you clicked Send XML messages to the queue, click Next. Continue to step 10 in this procedure.

    • If, on the XML Translation Information page, you clicked Send messages to the queue as a string, click Finish.
  8. On the XML Translation Information page, click one of the following options and click Next:
    • Receive XML messages from the queue

    • Receive string messages from the queue

      The XLANG Scheduler Engine must wrap the string in the engine's standard XML wrapper.

    Data flow in the XLANG Scheduler Engine is handled by using XML. The engine natively receives XML messages from message queues. The engine can also receive a message as a string, which the engine then wraps in XML.

  9. On the Message Type Information page, in the Message type box, type a label designation for the message.

    The text that you enter is used to identify the correct messages to receive from the message queue.

    First, the XLANG Scheduler Engine tries to match the message type information with the message label in the queue.

    Second, if the message is in an XML format on the queue, the XLANG Scheduler Engine tries to match the message type information with the XML root element of the message on the queue.

  10. To continue, do one of the following:
    • If, on the XML Translation Information page, you clicked Receive XML messages from the queue, click Next. Continue to step 11 in this procedure.

    • If, on the XML Translation Information page, you clicked Receive string messages from the queue, click Finish.
  11. On the Message Specification Information page, click Browse.

    The Browse for Specification dialog box appears.

  12. Browse to the specification that you want to use, click it, and then click Open.

    On the Message Specification Information page, in the Message specification box, the file path and file name of the specification that you selected are entered.

    Notes

    • If you do not browse for an existing specification, you can click Create. This action opens BizTalk Editor, which enables you to select a specification and modify it as needed for use with this message, or create a new specification.

    • If you select a specification by browsing for it, the Create button label changes to Edit. Click Edit to modify the specification that you have selected.
  13. On the Message Specification Information page, if you want to validate the message against the specification, select the Validate messages against the specification check box.

    Note

    • This check box is not enabled unless you select a specification for validation.
  14. On the Message Specification Information page, if you want to add fields to the Message fields list, click Add.

    Important

    • If you want to select additional fields for this message specification, you must use a specification that has been created by using BizTalk Editor. You can adapt any standard or schema by first importing it into BizTalk Editor and then saving it as a BizTalk Server specification. For more information, see Create and Validate Specifications.
  15. In the Field Selection dialog box, in the Select node tree, expand any nodes that you want, click the field that you want to add, and then click OK.

    Notes

    • When you click a field in the Select node tree, the field name is added automatically to the Field name box.

    • When you click a field in the Select node tree, the node path to that field is added automatically to the Node path box. This path can be edited manually. For more information, see Node Path Fields.

    • You cannot select a record node to add to the Message fields list. You can select only fields. For more information, see Node Path Fields.

    • If you want to add several fields to the Message fields list, in the Field Selection dialog box, you must select a field and click OK. On the Message Specification Information page, click Add and repeat the process to add another field.
  16. On the Message Specification Information page, if you want to delete fields in the Message fields list, click a field in the list and click Remove.

    Note

    • You cannot delete any required fields. Required fields appear in the Message fields list with a yellow background.
  17. Click Finish.

Notes

  • Shape names must meet certain naming conventions. The following conventions apply to transactions, ports, messages, rules, and fields:
    • The name must be a valid XML token name. For more information about XML tokens, go to the W3C Web site (www.w3.org).

    • The name cannot begin with underscores (__).

    • The name cannot include colons (:).

    • The name length must be less than or equal to 32 characters.

    • Constant names and message names cannot begin with a numeric character.
  • The wait time property is not enabled unless you click Receive.

  • The only messages available for use in an asynchronous communication are XML messages. All XML messages are available for use and can be specified for more than one port. You cannot use any of the synchronous message pairs that are created by using the Method Communication Wizard.

  • If you are connecting this communication flow to a port that is implemented by using BizTalk Messaging, the direction of the communication (Send or Receive) is determined by the port implementation and cannot be set in the XML Communication Wizard. The Send or Receive option on the first page of the wizard is selected automatically and is unavailable. You must click Next and continue to the next page of the wizard to finish the configuration of the communication flow.

  • When you create an asynchronous communication, a Message is created on the Data page. The Message corresponds to information sent or received in the communication flow. The Message contains required system fields and any additional specification fields that you want. For more information about defining the messages used in an asynchronous messaging communication, see Asynchronous Communication.

Related Topics

Asynchronous Communication

Create and Validate Specifications

Creating Specifications and Mapping Data

Dehydration and Rehydration

Establish the communication flow between an action and a port

Node Path Fields

Send or receive synchronous messages

Using the XML Communication Wizard


Modify the communication flow between an action and a port

  1. In BizTalk Orchestration Designer, on a design page, right-click the communication flow that is between an action and a port.

    A communication wizard opens.

  2. Follow the steps in the wizard to change any properties that you want to modify.

  3. Continue to one of the following procedures, depending on which type of communication flow you want to create:
    • If you want to create a synchronous communication flow to a port that uses a COM Component or Script Component implementation, use the Method Communication Wizard. Continue to Send or receive synchronous messages.

    • If you want to create an asynchronous communication flow to a port that uses a Message Queuing or BizTalk Messaging implementation, or if you want to create an asynchronous communication flow to an unbound port, use the XML Communication Wizard. Continue to Send or receive asynchronous messages.

Notes

  • You can establish a communication flow between an action and a port on the Business Process, Compensation for Transaction, and On Failure of Transaction pages. Actions and ports are not available on the Data page.

  • You cannot add shapes to the Data page. New messages are created automatically on the Data page each time an action is connected to a port.

Related Topics

Establish the communication flow between an action and a port

Send or receive asynchronous messages

Send or receive synchronous messages

Using the Method Communication Wizard

Using the XML Communication Wizard


Draw the Flow of Data Between Messages

The following procedures are covered in this section:

  • Select a message

  • Select a field within a message

  • Draw the flow between messages

  • Delete a message

  • Match a specific message with a specific port

  • Use Constants

Related Topics

Add, Delete, and Connect Shapes

Data Handling


Select a message

  • In BizTalk Orchestration Designer, on the Data page, click the gray header field for the message that you want to select.

    The entire message that you select is surrounded with a green dashed border.

Notes

  • You can select the Constants list, the Port References list, or a Message.

  • When you select an entire message, you can reposition it on the page by dragging it. Repositioning the messages can clarify the data flows that are drawn between messages.

Related Topics

Add, Delete, and Connect Shapes

Data Handling

Delete a message

Draw the flow between messages

Match a specific message with a specific port

Select a field within a message

Use Constants


Select a field within a message

  • In BizTalk Orchestration Designer, on the Data page, click a field with a message that you want to select.

    The field that you select is surrounded with a green dashed border. Any control handles ( Control handle) available to that field are enabled.

Related Topics

Add, Delete, and Connect Shapes

Data Handling

Delete a message

Draw the flow between messages

Match a specific message with a specific port

Select a message

Use Constants


Draw the flow between messages

  1. In BizTalk Orchestration Designer, on the Data page, click a field within a message to enable its control handles ( Control handle).

  2. Drag the control handle to the connection point ( Connection point) of a field in another message to which you want to connect.

  3. When the connection point is highlighted with a red box ( Active connection point), release the mouse button to set the connection.

Note

  • If you want to create several data flows, you can use the Connector Tool to add the flows quickly. For more information about the Connector Tool, see Use the Connector Tool.

Related Topics

Add, Delete, and Connect Shapes

Data Handling

Delete a message

Match a specific message with a specific port

Select a field within a message

Select a message

Use Constants


Delete a message

  • In BizTalk Orchestration Designer, on the Data page, click the gray header field for the message that you want to delete and press DELETE.

Notes

  • You cannot delete the Port References list.

  • You cannot delete the Constants list.

  • If you select an individual field within a message and press DELETE, the entire message is deleted, not just the field.

Related Topics

Add, Delete, and Connect Shapes

Data Handling

Draw the flow between messages

Select a field within a message

Select a message


Match a specific message with a specific port

  1. Click the field within the Port References list that contains the name of the port to which you want to refer.

  2. Drag the control handle ( Control handle) from that field to the connection point ( Connection point) of the field in a Message in which you want to pass the reference to the port.

Important

  • For more information about correlating messages and port references, see the following topics:
    • Instance Management

    • Data Handling

    • Understanding Port Implementations

Related Topics

Data Handling

Delete a message

Draw the flow between messages

Implement Ports

Instance Management

Select a field within a message

Select a message

Understanding Port Implementations

Use Constants


Use Constants

The following procedures are covered in this section:

  • Add constants

  • Edit constants

  • Delete constants

Related Topics

Data Handling

Field Data Types

Summary of Data Types and Data Type Values


Add constants

  1. In BizTalk Orchestration Designer, on the Data page, right-click the Constants list and click Properties.

    The Constants Message Properties dialog box appears.

  2. Click Add.

    The Constant Properties dialog box appears.

  3. In the Name box, type a name for the constant.

  4. In the Data type list, click the data type for the constant.

  5. In the Value box, type the value for the constant.

  6. Click OK, and then click OK again.

Notes

  • A default name with a number appended to it is provided for each constant that you create. You can change this name.

  • The Data type description area provides read-only information about the data type that you select. It might provide a format example for the data type, or a valid range for the value for a data type.

Related Topics

Data Handling

Delete constants

Edit constants

Field Data Types

Summary of Data Types and Data Type Values


Edit constants

  1. In BizTalk Orchestration Designer, on the Data page, right-click the Constants list and click Properties.

    The Constants Message Properties dialog box appears.

  2. In the Constants list, click the constant that you want to edit.

  3. Click Edit.

    The Constant Properties dialog box appears.

  4. Edit any constant properties that you want to change and click OK.

Notes

  • For more detailed information about the properties available in the Constant Properties dialog box, see Add constants.

  • A default name with a number appended to it is provided for each constant that you create. You can change this name.

  • The Data type description area provides read-only information about the data type that you select. It might provide a format example for the data type, or a valid range for the value for a data type.

Related Topics

Add constants

Data Handling

Delete constants

Field Data Types

Summary of Data Types and Data Type Values


Delete constants

  1. In BizTalk Orchestration Designer, on the Data page, right-click the Constants list and click Properties.

    The Constants Message Properties dialog box appears.

  2. In the Constants list, click the constant that you want to delete.

  3. Click Delete.

Related Topics

Add constants

Data Handling

Edit constants

Field Data Types

Summary of Data Types and Data Type Values


Run XLANG Schedules

This section contains procedures that explain how to compile and debug XLANG schedules, as well as how to activate and run an XLANG schedule. To run XLANG schedules, you might also want to create a COM+ application to host dedicated schedule instances.

The following topics are covered in this section:

  • Compile and Debug XLANG Schedules

  • Create and Configure an XLANG Schedule Host Application

Related Topics

Creating an Instantiating Application

Manage XLANG Applications and Databases

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Compile and Debug XLANG Schedules

When you create an XLANG schedule,you will want to compile, run, test, and debug the schedule. BizTalk Orchestration Designer provides features that assist in doing this.

In BizTalk Orchestration Designer, the following options are available:

  • Compiling

  • Updating method signatures

  • Shutting down running instances of XLANG schedules

In addition to these options, there are two tools that you can use to assist in testing and debugging an XLANG schedule:

  • XLANG Event Monitor. You can use this tool to monitor running XLANG schedule instances. For specific information about using this tool, see the associated Readme.htm file. Both XLANG Event Monitor (XLANGMon.exe) and the Readme installed by the Microsoft BizTalk Server 2002 Setup Wizard are located in the following installation directory: \Program Files\Microsoft BizTalk Server\SDK\XLANG Tools.

  • Windows 2000 Event Viewer. You can use this tool to view XLANG schedule errors. For more information, see the following topics:
    • Manage Event Viewer

    • Monitor Running XLANG Schedules

    • For more information about Event Viewer, in Windows 2000 Server Help, in the Event Viewer chapter, see "Using Event Viewer."

The following procedures are covered in this section:

  • Compile an XLANG schedule drawing into an XLANG schedule

  • Run an XLANG schedule

  • Pool an XLANG schedule

  • Debug compiled Visual Basic components

  • Refresh method signatures

  • Shut down all running XLANG schedules

Related Topics

Create and Configure an XLANG Schedule Host Application

Creating an Instantiating Application

Manage XLANG Applications and Databases

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Compile an XLANG schedule drawing into an XLANG schedule

  1. In BizTalk Orchestration Designer, on the File menu, click Make XLANG DrawingX.skx.

    The Save XLANG Schedule To dialog box appears.

  2. In the Save in list, browse to the location where you want to save the XLANG schedule.

  3. In the File name list, you can rename the file.

  4. Click Save.

Notes

  • When you compile an XLANG schedule drawing into an XLANG schedule, you might receive compiling errors. The error message indicates the possible problem in the drawing, and the affected shape is highlighted with a green, dashed border.

  • When you compile an XLANG schedule drawing into an XLANG schedule, the drawing is compiled with the default name DrawingX.skx, where X is a number that is appended to the schedule name. You can change the name of the file when you compile the drawing.

  • The file extension for an XLANG schedule is .skx. An .skx file is an XML file that is written in the XLANG language. You cannot open an .skx file within BizTalk Orchestration Designer. To change or update an .skx file, open the source .skv file, make your changes, and then recompile the .skv file into an .skx file.

  • The file extension for an XLANG schedule drawing is .skv.

  • If Microsoft® Visual InterDev® is set as the script debugger with "Just in time" debugging enabled, the debugger might be activated when you compile a schedule that contains script that references objects. You are prompted with the following message:

    Would you like to debug the application?

    Click No, which enables the script to bypass the debugger and allows the schedule to compile normally. (Clicking Yes starts the debugger. To stop it, you must detach all processes or cancel debugging, which will shut down Microsoft Visio and possibly cause you to lose an unsaved schedule.) You can avoid this issue by disabling "Just in time" debugging in the registry by setting HKEY_CURRENT_USER\Software\Microsoft\Windows Script\Settings\JITDebug to 1.

Related Topics

Create and Configure an XLANG Schedule Host Application

Creating an Instantiating Application

Debug compiled Visual Basic components

Manage XLANG Applications and Databases

Open and Save XLANG Schedule Drawings

Refresh method signatures

Run an XLANG schedule

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances

Shut down all running XLANG schedules


Run an XLANG schedule

To run an XLANG schedule, you must create a means to activate the XLANG schedule.

There are two primary ways to do this:

  • Configure BizTalk Orchestration Services and BizTalk Messaging Services to activate and run XLANG schedules.

    For more information, see the following topics:

    • Integrating BizTalk Services

    • Set destination application properties
  • Programmatically activate the XLANG schedule by creating an instantiation application such as an ASP page.

    For more information, see the following topics:

    • Running XLANG Schedules

    • Creating an Instantiating Application

    • Moniker Syntax

Related Topics

Compile an XLANG schedule drawing into an XLANG schedule

Create and Configure an XLANG Schedule Host Application

Creating an Instantiating Application

Debug compiled Visual Basic components

Manage XLANG Applications and Databases

Moniker Syntax

Refresh method signatures

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances

Shut down all running XLANG schedules


Pool an XLANG schedule

You can pool your schedules to efficiently use resources when traffic is high and many schedule instances are activated at once. To assign an object pool to a schedule, do the following:

  1. Right-click the Begin shape and click Properties.

    The Begin Properties dialog box appears.

  2. In the Pool box, select a pool from the drop-down list.

To set properties on the object pool, do the following:

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and expand COM+ Applications.

  3. Right-click XLANG Schedule Pool and click Properties.

    The XLANG Schedule Pool Properties dialog box appears.

  4. Click the Advanced tab.

  5. In the Permissions area, clear the Disable changes check box and click OK.

  6. In the console tree, expand XLANG Schedule Pool, expand Components, right-click SimpleSkedPool.SimplePoolN.1, where N is the number of the pool you selected in the drop-down list in the previous procedure, and click Properties.

    The SimpleSkedPool.SimplePoolN.1 Properties dialog box appears.

  7. Click the Activation tab.

  8. In the Object pooling area, do the following:
    • Minimum pool size. Modify the minimum pool size to specify the minimum number of objects that will be kept in memory.

    • Maximum pool size. Modify the maximum pool size to specify the maximum number of schedule instances that can be active concurrently.

    • Creation timeout (ms). Modify the creation timeout to specify the number of milliseconds (ms) a schedule instance will wait to be activated.
  9. Click OK to close the SimpleSkedPool.SimplePoolN.1 Properties dialog box.

Note

  • For more information about pooling, see Pooling XLANG Schedules.


Debug compiled Visual Basic components

There might be situations in which you need to debug components built with Microsoft Visual Basic after they have been compiled.

  1. In Visual Basic 6.0, open the Visual Basic project that you want to debug.

  2. On the File menu, click Make <YourProject>.dll.

    The Make Project dialog box appears.

  3. Click Options.

    The Project Properties dialog box appears.

  4. In the Project Properties dialog box, on the Compile tab, click Compile to Native Code, click No Optimization, and then select the Create Symbolic Debug Info check box.

  5. Click OK, and then click OK again to compile your project.

  6. Open the Visual Basic .dll project.

  7. Set the breakpoints that you want to use.

  8. On the Run menu, click Start.

The next time the XLANG schedule calls into your Visual Basic component, the Visual Basic debugger will stop at the breakpoint.

Important

  • The Visual Basic .dll must be created with the Create Symbolic Debug Info check box selected.

  • Ensure that the XLANG Scheduler Engine has not already loaded the .dll. If the .dll has been loaded, you must shut down the engine and retry.

Note

  • For more information about debugging components, or about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."


Refresh method signatures

Use this option if you are creating COM+ components at the same time you are creating the XLANG schedule and you change any of the method parameters in any of the available method calls. This refreshes the available method parameters in the XLANG schedule.

  • In BizTalk Orchestration Designer, on the Tools menu, click Refresh Method Signatures.

Notes

  • When you compile an XLANG schedule, Refresh Method Signatures is run automatically.

Related Topics

Compile an XLANG schedule drawing into an XLANG schedule

Create and Configure an XLANG Schedule Host Application

Creating an Instantiating Application

Debug compiled Visual Basic components

Manage XLANG Applications and Databases

Run an XLANG schedule

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances

Shut down all running XLANG schedules


Shut down all running XLANG schedules

  • In BizTalk Orchestration Designer, on the Tools menu, click Shut Down All Running XLANG Schedule Instances.

Note

  • When running an XLANG schedule instance, it is not possible to modify COM components used by that XLANG schedule. This option shuts down all running instances of the schedule, unlocking the file containing the component so you can make changes.

Related Topics

Compile an XLANG schedule drawing into an XLANG schedule

Create and Configure an XLANG Schedule Host Application

Creating an Instantiating Application

Debug compiled Visual Basic components

Manage XLANG Applications and Databases

Refresh method signatures

Run an XLANG schedule

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Create and Configure an XLANG Schedule Host Application

This section contains procedures that explain how to activate and run an XLANG schedule. Although you can use the default XLANG Scheduler application to run XLANG schedules, it is often useful to create a new COM+ application to run schedule instances.

Due to security, deployment, and configuration issues, most COM+ applications that host XLANG schedules must be created when the XLANG schedule is developed. You must take into consideration security and performance needs for the applications and the schedules. You might want to create a new COM+ application to host dedicated instances of running schedules, or you might want to isolate applications that run specific schedule instances from other XLANG schedules that use different applications.

For more information about security and performance issues related to creating XLANG schedules and a COM+ application to host the schedules, see Security for Applications That Host XLANG Schedule Instances.

For information about how to manage COM+ applications after they have been created, see Manage XLANG Applications and Databases.

The following procedures are covered in this section:

  • Create a COM+ application to host XLANG schedules

  • Configure a COM+ application to host XLANG schedules

Notes

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Creating an Instantiating Application

Manage XLANG Applications and Databases

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Create a COM+ application to host XLANG schedules

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then click COM+ Applications to select it.

    You must first select COM+ Applications and then right-click it. If you do not select it first, the New option is not available.

  3. Right-click COM+ Applications, point to New, and then click Application.

    The COM Application Install Wizard opens.

  4. On the Welcome to the COM Application Install Wizard page, click Next.

  5. On the Install or Create a New Application page, click Create an empty application.

  6. On the Create an Empty Application page, type a name for the application, verify that Server application is selected, and then click Next.

  7. On the Set Application Identity page, set the application identity to the appropriate account.

    It is recommended that you create a service account for COM+ applications that host XLANG schedules.

    For more information about security and performance issues related to creating an application identity, see Security for Applications That Host XLANG Schedule Instances.

  8. Click Next and click Finish.

  9. Right-click the COM+ application that you just created and click Properties.

  10. On the XLANG tab, select the This application is a host for XLANG schedule instances check box.

  11. To configure the COM+ application, continue to Configure a COM+ application to host XLANG schedules.

Important

  • You must install at least one COM component in your COM+ application.

Notes

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

  • It is recommended that you host XLANG schedules only in dedicated processes; the COM+ application that hosts the schedule should do nothing else.

  • When you create a COM+ application to host XLANG schedules, the Restart dehydrated applications option is not available. For more information about how to restart dehydrated applications, see Restart all XLANG applications.

Related Topics

Configure a COM+ application to host XLANG schedules

Creating an Instantiating Application

Manage XLANG Applications and Databases

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Configure a COM+ application to host XLANG schedules

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services.

  2. In the console tree, expand Component Services, expand Computers, expand My Computer, and then expand COM+ Applications.

  3. Right-click the COM+ application that you want to configure and click Properties.

    It is highly recommended that you create a service account to manage COM+ applications that host XLANG schedules. If you accepted default settings in the COM Application Install Wizard when you created the COM+ application, you might want to change these settings. For more information, see Change the application identity for a COM+ application.

  4. Configure DSN settings for the COM+ application.

    For more information, see Change the DSN settings for a COM+ application.

  5. Configure a database for the COM+ application to use.

    You can:

    • Point to an existing database. For more information, see Change the DSN settings for a COM+ application.

      –Or–

    • Create and configure a new database. For more information, see Create a new empty persistence database and Change the DSN settings for a COM+ application.

Caution

  • If you create and configure a new database to use with the COM+ application, you must initialize the database tables after you configure the data source name (DSN) settings for the COM+ application.

    For more information about configuring a DSN and using data sources (ODBC), click Help in the ODBC Data Source Administrator dialog box.

    To initialize new database tables for the COM+ host application that you configure:

    1. Right-click the COM+ application and click Properties.

    2. Click the XLANG tab.

    3. Click Initialize Tables.
  • Do not click Initialize Tables if you are configuring a COM+ host application and a DSN for an existing database. This action destroys any data already in the existing database.

Notes

  • For Component Services Administration Help, on the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Component Services. In the console tree, right-click Component Services and click Help.

  • For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on "Component Services."

Related Topics

Change the application identity for a COM+ application

Change the DSN settings for a COM+ application

Create a COM+ application to host XLANG schedules

Create a new empty persistence database

Creating an Instantiating Application

Manage XLANG Applications and Databases

Running XLANG Schedules

Security for Applications That Host XLANG Schedule Instances


Configuring BizTalk Messaging Services

Microsoft® BizTalk™ Server 2002 provides two methods for configuring BizTalk Messaging Services to manage the exchange of documents between trading partners and applications within your business. You can either use BizTalk Messaging Manager, which is a graphical user interface (UI), or directly access the BizTalk Messaging Configuration object model.

Using BizTalk Messaging Manager or the BizTalk Messaging Configuration object model, you can create messaging ports and channels to manage the exchange of data. You also can create document definitions, envelopes, and organizations, which you use to create messaging ports and channels; and distribution lists, which are groups of messaging ports.

Security Requirements

To use BizTalk Messaging Manager, you must:

  • Belong to a user account in the BizTalk Server Administrators group, which is created when BizTalk Server 2002 is installed. Additional users can be added to this group as necessary. For more information about adding a user account, see Add users to the BizTalk Server Administrators group.

  • Have full database access to the BizTalk Messaging Management database (InterchangeBTM), which means you are able to log in and have been granted the db_owner database role. For more information, see "How to grant a Windows user or group access to a database" in the Microsoft SQL Server online documentation.

Should you use BizTalk Messaging Manager or the BizTalk Messaging Configuration object model API?

BizTalk Messaging Manager enables you to access the BizTalk Messaging Configuration object model through a graphical user interface. Whether or not you use that interface depends on the amount and type of information available to you in your database. The BizTalk Messaging Configuration object model application programming interface (API) enables you to automate all or part of the configuration process, rather than entering the data for each individual entity into BizTalk Messaging Manager. In general, the more business partners you have, the more it benefits you to use the API to configure your messaging service.

For example, suppose a large manufacturing company (a "hub" in the hub-spoke paradigm) uses 1,000 suppliers and maintains a database with information about each supplier. During the "create organizations" step, it would be relatively quick and easy to write code that:

  • Extracts information from the database.

  • Uses the BizTalk Messaging Configuration object model to programmatically create these 1,000 organizations in the BizTalk Messaging Management database.

In contrast, it could take considerably longer to create all 1,000 objects one-by-one using BizTalk Messaging Manager. (Imagine running the same wizard 1,000 times.) And that is to create only the organizations, not the document definitions, channels, or messaging ports.

However, a small supply company (a "spoke") that maintains relationships with just a few trading partners would likely use BizTalk Messaging Manager to configure its entire messaging system rather than taking time to write specialized code.

For more information about accessing the BizTalk Messaging Configuration object model directly through the API, see Introducing Messaging Services.

The following topic is covered in this section:

  • Using BizTalk Messaging Manager


Using BizTalk Messaging Manager

Microsoft® BizTalk™ Messaging Manager is a graphical user interface (UI) with which you can manage the exchange of documents by configuring BizTalk Messaging Services. BizTalk Messaging Services can also be configured programmatically using the BizTalk Configuration object model API. For more information, see Introducing Messaging Services.

Caution

  • You should use BizTalk Messaging Manager to configure BizTalk Messaging Services prior to processing documents. Accessing and modifying objects that might be in use while Microsoft BizTalk Server 2002 is processing documents can produce unexpected results.

Documents can be exchanged between trading partners and applications within your business. BizTalk Messaging Manager is available both locally from the computer on which BizTalk Server 2002 is installed and remotely as a client application. This enables system administrators to retain security and central control of the server, while enabling remote users to access BizTalk Messaging Manager.

BizTalk Server 2002 Help provides information about how to create and manage the following BizTalk Messaging Manager objects:

  • Channels

  • Messaging ports

  • Document definitions

  • Envelopes

  • Organizations

BizTalk Server 2002 Help also provides information about how to use distribution lists.

BizTalk Messaging Manager objects

The following illustration shows the relationships between the objects that you can create by using BizTalk Messaging Manager.

BizTalk Messaging Manager overview

The following summary provides a brief overview of the objects that you can create by using BizTalk Messaging Manager. This summary also further explains the relationship between the objects. For more detailed information about each object, click the link at the end of each description to go to the Help topic for that object.

Channels

Channels are the primary objects in BizTalk Messaging Manager. The purpose of all other BizTalk Messaging Manager objects is to either create channels or support the operation of channels. Channels identify the source of documents, which can be an organization, an application within your business, or an XLANG schedule. Channels also identify inbound and outbound documents by using document definitions. For more information, see Understanding Channels.

Messaging ports

Messaging ports identify a destination for the documents that are processed by a channel. The destination can be an organization, an application within your business, or an XLANG schedule. A messaging port specifies a destination address to which the documents are sent, how they are transported to that address, and if and how they are secured and enveloped. For more information, see Understanding Messaging Ports.

Organizations

Organizations represent other trading partners with which you exchange documents. A special organization type, called the home organization, represents your business. You can create applications for the home organization that represent the internal applications that your business uses. Organizations and applications serve as the source for a channel or the destination for a messaging port. For more information, see Understanding Organizations.

Document definitions

A document definition represents a specific type of document that is processed by BizTalk Server 2002. A document definition provides a pointer to a specification. Specifications define the document structure, type, and version. Channels specify an inbound and an outbound document definition to indicate which documents the server processes. A document definition can be used in any number of channels. For more information, see Understanding Document Definitions.

Envelopes

Envelopes provide BizTalk Server 2002 with the information that the server needs to either open inbound or create outbound interchanges. Envelopes can be selected from within a messaging port to direct the server in creating outbound interchanges. Envelopes, which are independent of a messaging port, can be used by BizTalk Server 2002 to open inbound interchanges. For more information, see Understanding Envelopes.

Distribution lists

Distribution lists are groups of messaging ports with which you can send the same document to a group of different trading partner organizations or internal applications. You must create at least one channel for a distribution list, just as you do for an individual messaging port. For more information, see Understanding Distribution Lists.

Notes

  • The objects that you can create by using BizTalk Messaging Manager can also be created programmatically by using the BizTalk Messaging Configuration object model. For more information, see Understanding Messaging Services.

  • The objects that you can create by using BizTalk Messaging Manager also use objects that you can create by using other BizTalk Messaging Services user interfaces. Channels use maps, which you can create by using BizTalk Mapper. Document definitions use document specifications, and envelopes use envelope specifications. You can create specifications by using BizTalk Editor.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Messaging Manager, see About BizTalk Messaging Manager.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Messaging Manager Tasks .

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Messaging Manager Tasks.


About BizTalk Messaging Manager

This section provides detailed conceptual information that is essential to understanding Microsoft BizTalk Messaging Manager. It provides information about the following topics:

  • BizTalk Messaging Manager Environment

  • Understanding Channels

  • Understanding Messaging Ports

  • Understanding Organizations

  • Understanding Document Definitions

  • Understanding Envelopes

  • Understanding Receipts

  • Understanding Distribution Lists


BizTalk Messaging Manager Environment

The following topics are covered in this section:

  • Configuring BizTalk Messaging Manager Options

  • BizTalk Messaging Manager User Interface

  • BizTalk Messaging Manager Shortcut Keys

  • Security

Caution

  • You should use BizTalk Messaging Manager to configure BizTalk Messaging Services prior to processing documents. Accessing and modifying objects that might be in use while Microsoft BizTalk Server 2002 is processing documents can produce unexpected results.


Configuring BizTalk Messaging Manager Options

This section explains how to modify BizTalk Messaging Manager options. These options include:

  • Configuring new messaging ports or channels.

  • Managing previously configured messaging ports or channels.

  • Setting the search return value.

  • Setting the server connection.

  • Setting the server time-out value.

The following procedures are covered in this section:

  • Select a BizTalk Messaging Manager configuration option

  • Set server connection options

Note

  • The toolbars in BizTalk Messaging Manager can be repositioned; however, when the application is restarted, the toolbars return to their original positions.


Select a BizTalk Messaging Manager configuration option

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

    The BizTalk Messaging Manager dialog box appears.

  2. In the Configuration options area, select one of the following options:
    • If you want to create and configure a new messaging port to an organization, click Configure a new messaging port to an organization and click OK.

      For more information about creating and configuring a new messaging port to an organization, see Create messaging ports.

    • If you want to create and configure a new messaging port to an application, click Configure a new messaging port to an application and click OK.

      For more information about creating and configuring a new messaging port to an application, see Create messaging ports.

    • If you want to manage existing messaging ports, click Manage previously configured messaging ports and click OK.

      For more information about managing existing messaging ports, see Edit messaging ports.

    • If you want to manage existing channels, click Manage previously configured channels and click OK.

      For more information about creating and configuring existing channels, see Edit channels.

Note

  • If you do not want this dialog box to appear when you open BizTalk Messaging Manager, select the Don't show this dialog box again check box. To reset the dialog box to appear, on the Tools menu, click Options and select the Show startup dialog box check box.

Related Topics

Create messaging ports

Edit channels

Edit messaging ports


Set server connection options

  1. In BizTalk Messaging Manager, on the Tools menu, click Options.

    The Options dialog box appears.

  2. In the Maximum number of items to return in a search box, complete one of the following steps:
    • Type a value for the number of items to be returned in a search.

    • Click the up or down arrow to increase or decrease the value.
  3. In the Name of BizTalk Server to connect to box, type the name of a server on which BizTalk Server 2002 is installed.

  4. In the Server timeout in seconds box, complete one of the following steps:
    • Type a value for the number of seconds before the server connection times out.

    • Click the up or down arrow to increase or decrease the value.
  5. To have an opening dialog box appear or not appear when BizTalk Messaging Manager starts, select or clear the Show startup dialog box check box.

  6. After you have set all properties, click OK.

Notes

  • The server to which you connect determines the BizTalk Messaging Management database for which you search, edit, or create new objects by using BizTalk Messaging Manager. The server connection defaults to the last connection that was made. The server that hosts the WebDAV repository that you use to store and retrieve specifications for documents, maps, and envelopes is set independently from within the dialog boxes that you use to select specifications. The WebDAV connection defaults to the last connection that was made.

  • The default number of items returned in a search is 500.

  • The default number of seconds before the server connection times out is 20.

  • The server to which you are currently connected is displayed at the top of the Search pane located on the left side of BizTalk Messaging Manager.

  • When using Internet Explorer 5.5 Service Pack 1 (SP1), you might receive the following error message: "The response document is not a valid document." To correct this, enter the fully qualified domain name in the "Name of BizTalk Server to connect to" box. Then, in Internet Explorer 5.5 SP1, either mark your proxy settings as exceptions (on the Tools menu, click Internet Options and click the Connections tab), or add them as sites (on the Tools menu, click Internet Options and click the Security tab). For more information, see the Internet Explorer 5.5 SP1 documentation.


BizTalk Messaging Manager User Interface

The BizTalk Messaging Manager user interface has two main panes.

The left pane displays:

  • The name of the server to which BizTalk Messaging Manager is connected.

  • A list of objects for which you can search.

  • Search criteria that you can use to narrow your search.

You can search for any objects that you create by using BizTalk Messaging Manager. You can choose the type of object for which you want to search by clicking the name in the Search for other items area. The search criteria differ according to the object that you select.

The right pane displays:

  • The details of the items returned in your most recent search.

The details of the items differ according to the type of object for which you search.

You can sort the items in the search results pane in ascending or descending order by clicking the column headers. You can sort based on only one column at a time.

Notes

  • If you have a large number of a particular type of object for which to search, it might take several minutes to return all the items. You can reduce the number of items returned in a search by using search criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

Related Topics

BizTalk Messaging Manager Shortcut Keys

Search for channels

Search for distribution lists

Search for document definitions

Search for envelopes

Search for messaging ports

Search for organizations


BizTalk Messaging Manager Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Messaging Manager. The following table is a quick reference to these shortcut keys.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server and Advanced Server Help, see "Using the keyboard to move the mouse pointer." For more information about MouseKeys in Windows 2000 Professional Help, see "Move the mouse pointer by using MouseKeys."
Press | To
CTRL+A | Select all.
CTRL+C | Copy text.
CTRL+X | Cut text.
CTRL+V | Paste text.
CTRL+Z | Undo text action.
CTRL+R | Create a new messaging port to an organization.
CTRL+SHIFT+R | Create a new messaging port to an application.
CTRL+L | Create a new channel from an organization.
CTRL+SHIFT+L | Create a new channel from an application.
CTRL+T | Create a new distribution list.
CTRL+D | Create a new document definition.
CTRL+G | Create a new organization.
DELETE | Delete the selected item or text.
SHIFT+F10 | Display the shortcut menu for the selected item.
SHIFT with any arrow key | Select more than one item in a window or select text.
TAB | In a dialog box, pressing TAB moves the focus through the buttons and fields of the dialog box.
SHIFT+TAB | In a dialog box, pressing TAB moves the focus through the buttons and fields of the dialog box.
CTRL+TAB | Toggle tabs of a dialog box in front-to-back order.
CTRL+SHIFT+TAB | Toggle tabs of a dialog box in back-to-front order.
SPACEBAR | Select or clear a check box. The spacebar also acts like a mouse click when the focus is on a button.
ALT+SPACEBAR | Display the system menu for the active window.
ALT+Underlined letter in a menu name | Display the corresponding menu.
Underlined letter in a command name on an open menu | Carry out the corresponding command.
ALT+ DOWN ARROW | Display the drop-down list for an activated list box.
ENTER | Carry out the command for the active option or button.
ESC | Cancel the current task.
F1 | Display online Help.
ALT+F4 | Close the active window, or quit the active program.
LEFT ARROW | Move the focus to the tab to the left.
RIGHT ARROW | Move the focus to the tab to the right.
Any arrow key | Highlight a folder or a file in the main window of a dialog box, while the focus is in that window. This functionality occurs in the Select a Document Specification from the WebDAV Repository, the Select an Envelope Specification from the WebDAV Repository, and the Select a Map from the WebDAV Repository dialog boxes. For more information, see Select a document specification, Select an envelope specification, and Select a map.

Related Topic

BizTalk Messaging Manager User Interface


Security

To access or create objects by using BizTalk Messaging Manager, you must:

  • Belong to a user account in the BizTalk Server Administrators group, which is created when BizTalk Server 2002 is installed. Additional users can be added to this group as necessary. For more information about adding a user account, see Add users to the BizTalk Server Administrators group.

  • Have full database access to the BizTalk Messaging Management database (InterchangeBTM), which means you are able to log in and have been granted the db_owner database role. For more information, see "How to grant a Windows user or group access to a database" in the Microsoft SQL Server documentation.


Understanding Channels

A channel is a set of properties that you can use to configure BizTalk Messaging Services to process a document that it receives. Channels can be created for a messaging port or a distribution list. Once a channel has processed a document, the document is transported to the destination specified in the associated messaging port or the messaging ports in the associated distribution list. You can create one or more channels for a messaging port or distribution list.

In a channel, you specify the source of the documents, which can be a source organization or a source application. Before you can designate an application as the source for a channel, you must create an application for the home organization, which represents an actual internal application in your business. You can also designate an XLANG schedule as the source for a channel. You can create an XLANG schedule by using BizTalk Orchestration Designer. For more information, see Designing BizTalk Orchestrations. For more information about integrating BizTalk Messaging Services with BizTalk Orchestration Services, see Integrating BizTalk Services.

You can also explicitly declare an open source for a channel, which means that the source must be specified either within the document or in a parameter when the document is submitted. This is referred to as an open channel. For more information, see Submitting.

You also specify an inbound document definition, which represents an incoming document from an internal application or a trading partner organization. And you specify an outbound document definition, which represents a document to be delivered to the specified destination. For more information about document definitions, see Understanding Document Definitions.

If the format or structure of an outbound document is different from the format or structure of the inbound document, you must specify a map for the channel. A map transforms the format or structure of the original inbound document into the outbound document format or structure that is required by the destination organization or application. For example, if your accounting application generates purchase orders in a delimited flat-file format but your trading partner requires that purchase orders be in an X12 format, you can use a map to transform the document format. For more information about maps, see Using BizTalk Mapper.

You can create more than one channel for a messaging port or distribution list, each with a different configuration. For example, suppose that you have two internal accounting applications that generate purchase orders in different formats and that you have a trading partner that wants to receive purchase orders from you in still another format. You can create a single messaging port to the trading partner. Then, for that messaging port, you can create a channel from each of the applications. The outbound document definition for both channels would be the same and match the format of your trading partner. However, each channel would have a different map to transform the inbound document formats from the applications. Because you can create different channels connected to a single messaging port, you can send all your purchase orders in the same format.

In addition, you can set other properties within a channel to:

  • Designate specification fields to track for the inbound document definition. Any fields that you designate are logged to a Tracking database for each document instance processed using this specific channel, in place of any global tracking fields designated in the document definition. For more information about global tracking fields, see Tracking Document Data Fields.

  • Create a channel filtering expression, which determines if BizTalk Server 2002 invokes the channel, based on the value of a field or fields within the document being processed.

  • Configure receipts. You can request a receipt from the destination for a document that you send, and you can generate a receipt to the source for a document that you receive. For more information about processing receipts, see Understanding Receipts.

  • Configure security properties. You can specify that the server verify the encryption and signature for an inbound document, or digitally sign the outbound document.

  • Specify document logging options. You can store both the inbound and the outbound documents in their native format, in their intermediate XML format, or both.

  • Configure advanced properties. You can specify a group control number for documents with EDI formats, set the number and time interval that the server uses to resend documents, and override the transport component and envelope properties for the messaging port or distribution list.

You can also create receipt channels by using BizTalk Messaging Manager. A receipt channel is a special type of channel that you use to return a receipt to the sender of a document that is received by BizTalk Messaging Services. When you create a channel to process an inbound document that requires a receipt, you can specify the receipt channel that the server should use to process the receipt. Because of this, you should create a messaging port and an associated receipt channel before you create a messaging port and channel to process a document that requires a receipt. For more information about processing receipts, see Understanding Receipts.

Caution

  • When you create a receipt channel, both the inbound and outbound document definitions default to the BizTalk Canonical Receipt and cannot be transformed by using a map. To use a different format for an outbound receipt, you must create and select an inbound document definition that refers to the canonical receipt specification in the WebDAV repository. You also must create an outbound document definition that refers to a specification with the format that you want for the outbound receipt, as well as a map that transforms the format of the receipt.

When BizTalk Server 2002 receives a document, it locates the appropriate channel, which directs the server in how to process the document. The server then locates the messaging port or distribution list associated with the channel. The messaging port directs the server through the sequence of steps necessary to transport the document to the specified destination. If the channel is associated with a distribution list, the server uses the properties of each of the messaging ports in the distribution list to transport the document to the specified destinations.

The following topics are covered in this section:

  • Channel Elements

  • Valid Channel and Messaging Port Combinations


Channel Elements

Channels consist of the following elements:

Source organization or application

When you create a channel, you designate either an application or an organization as the source for documents. A source application always represents a business application of your home organization. This could be an accounting application, an order-entry system, or a line-of-business application. You can also designate an XLANG schedule as the source for documents. You can create an XLANG schedule by using BizTalk Orchestration Designer. A source organization always represents an external trading partner.

A channel is always created for a messaging port or a distribution list. The destination for the documents that you receive from the source of a channel is designated in the messaging port, or in the messaging ports of the distribution list, for which the channel is created.

Inbound and outbound document definitions

Document definitions in a channel represent the inbound and outbound documents that are processed by BizTalk Server 2002. A document definition provides a pointer to a specification that defines the document. The specification defines such characteristics as the document structure, type, and version. For more information, see Understanding Document Definitions.

When BizTalk Server 2002 receives a document, it locates the appropriate channel to process it. The server uses the specification of the inbound document definition to translate the incoming document into an intermediate XML format. The server maps the inbound document format and structure to the outbound format and structure, if necessary. Then, the server uses the specification of the outbound document to translate the outbound document into the format and structure that the destination application or organization can recognize and use.

Mapping data formats

The format or structure of an inbound document might be different from the format or structure that is required for the outbound document. If this is the case, a map can be used to transform the format of the inbound document into the format of the outbound document.

For example, if you have an accounting application that generates invoices in a comma-delimited, flat-file format, but your trading partner needs to receive invoices in an X12 format, you can use a map on the channel to transform the format.

A map can also transform the content and structure of a document that uses the same format. For more information, see Using BizTalk Mapper.

Tracking and filtering properties

You can designate specification fields to be logged to a Tracking database for the inbound document definition of a channel. The specification fields that you designate in a channel are logged to a Tracking database for each instance of a document processed using this channel. These fields are logged in place of any global tracking fields that are designated in the inbound document definition. Any global tracking fields designated for the outbound document definition are ignored. For more information, see Tracking Document Data Fields.

A channel filtering expression provides an additional way to determine which channels are invoked when BizTalk Server 2002 receives a document. In the case of a channel filtering expression, this determination is based upon the value of a specified field or fields within the document instance.

When the server processes a document, the value of each of the specified fields is evaluated against the value of the channel filtering expression. If the expression is found to be true, the channel is invoked. If the expression is found to be false, the channel is not invoked. For example, if the channel filtering expression is created to check for a purchase order total greater than 1000, and the PO Total field in the document is 1500, the channel is invoked.

Document logging properties

BizTalk Server 2002 translates non-XML inbound documents from their original, native format into an intermediate Unicode XML format for processing. BizTalk Server 2002 translates outbound documents from an intermediate Unicode XML format into the required format for the specified destination. You can choose to store the data of each inbound and outbound document in either format or in both.

Related Topics

Create and Manage Channels

Understanding Channels

Valid Channel and Messaging Port Combinations


Valid Channel and Messaging Port Combinations

You can create only certain channel (source) and messaging port (destination) combinations that are valid for use with Microsoft BizTalk Server 2002.

The following valid business scenarios indicate how to configure messaging ports with the correct destination and channels with the correct source designations to correctly route data.

Scenario 1: Trading partner to an internal application

In this scenario, you create a messaging port with an application of the home organization as its destination. You then create a channel for this messaging port with the trading partner organization as its source.

Scenario 2: Internal application to trading partner

In this scenario, you create a messaging port with a trading partner organization as its destination. You then create a channel for this messaging port with an application of the home organization as its source.

Scenario 3: Internal application to internal application

In this scenario, you create a messaging port with an application of the home organization as its destination. You then create a channel for this messaging port with a different application of the home organization as its source.

Scenario 4: Internal application to distribution list

In this scenario, you create a distribution list, which includes a group of existing messaging ports to organizations or applications. You then create a channel for this distribution list with an application of the home organization as its source.

Scenario 5: Internal application to open destination

In this scenario, you create a messaging port that you specify as an open messaging port. You then create a channel for this messaging port with an application of the home organization as its source.

Scenario 6: Open source to internal application

In this scenario, you create a messaging port with an application of the home organization as its destination. You then create a channel for this messaging port that you specify as an open channel.

Note

  • A channel that is specified as an open channel cannot be created for a messaging port that is specified as an open messaging port.

Scenario 7: Trading partner through intermediary to trading partner

In this scenario, one trading partner sends documents to another through your BizTalk Server, with your business serving as an intermediary. You create a messaging port with one trading partner organization as its destination. You then create a channel for this messaging port with a different trading partner as its source.

Related Topics

Channel Elements

Understanding Channels


Understanding Messaging Ports

A messaging port is a set of properties that you can use to configure BizTalk Messaging Services to transport documents to a specified destination by using a specified transport service. The documents that a messaging port transports originate from the source that you specify in an associated channel. You can create multiple channels for a single messaging port to send documents from many sources to the same destination.

A messaging port can be configured to send documents to a designated destination organization, an XLANG schedule, or a destination application.

When you configure a messaging port to an organization, you can either designate a specific trading partner as the destination or declare an open destination, which is referred to as an open messaging port. An open messaging port can be used to transport documents only to trading partner organizations. The destination organization information for an open messaging port must be specified either within the document or in a parameter when the document is submitted to BizTalk Server 2002. For more information about submitting documents, see Submitting. For more information about open messaging ports, see Openness.

When the address specified for an open messaging port is an SMTP address, the server must have a From address for the home organization. To obtain this address, the server uses the value that is specified for a special organization identifier of the home organization, named Reliable Messaging Acknowledgement SMTP From Address. For more information about how to configure this organization identifier, see Configure the home organization.

When you configure a messaging port to an application, you can designate either an XLANG schedule or an application of the home organization as the destination. For more information about the home organization, see Understanding Organizations.

A messaging port to an XLANG schedule can be configured to activate a new instance of a specified XLANG schedule, and then deliver the document to a specified messaging port of that schedule. In this case, the specified schedule must contain a messaging port that is bound to BizTalk Messaging Services. When you specify the schedule, you also name the messaging port. You can also configure a messaging port to deliver a document to a running instance of an XLANG schedule. In this case, the document must contain a queue name to which the document should be delivered and that the targeted schedule is monitoring. For more information about integrating BizTalk Messaging Services with BizTalk Orchestration Services, see Integrating BizTalk Services.

You also use the messaging port properties to designate a specific address to which documents are delivered, the transport type for getting documents to that location, and how the documents are enveloped and secured prior to transport.

When BizTalk Server 2002 receives a document, it locates the appropriate channel to process it. After the channel processes the document, it points the server to its associated messaging port or distribution list, which directs the server through the sequence of steps necessary to envelope, secure, and transport the document to the specified destination.

The following topics are covered in this section:

  • Messaging Port Elements

  • Open Messaging Ports


Messaging Port Elements

Messaging ports consist of the following elements:

Destination

The destination for a messaging port can be a trading partner organization, an XLANG schedule, or an application of the home organization.

A messaging port to an organization can explicitly designate the destination organization, or a messaging port can be declared as an open messaging port. For open messaging ports, the destination organization is determined at the time the messaging port processes a document. The destination organization information must be specified either in the document or in parameters when the document is submitted. For more information, see Submitting.

A messaging port to an XLANG schedule can be configured in two ways. You can configure a messaging port to activate a new instance of an XLANG schedule by specifying the path to an XLANG schedule. When the messaging port processes a document, it activates this schedule and then delivers the document to a messaging port in that schedule that you also specify in the messaging port properties. Or you can configure the messaging port to deliver documents to an active XLANG schedule. You use this option only when you send a trading partner a message and the trading partner returns a message to a specially configured ASP page using an HTTP transport. For more information, see Integrating BizTalk Services. You can create an XLANG schedule by using BizTalk Orchestration Designer. For more information, see Designing BizTalk Orchestrations.

A messaging port can also transport documents to a destination application of the home organization. Before you can designate an application as the destination for a messaging port, you must add the application to the home organization. For more information, see Add applications.

Transport properties

The transport properties that you specify for a messaging port determine the transport service used to convey documents to the destination organization or destination application, and the specific address to which the documents are sent.

The transport properties that you set for a messaging port apply to all channels associated with that messaging port. After BizTalk Server 2002 invokes a channel to process documents, the server then refers to the properties of the messaging port that is associated with the channel. The server sends the documents to the address specified in the messaging port, using the transport type specified in the messaging port.

You can also specify a service window, which designates a specific time range within which documents can be transported. Service window hours are displayed in coordinated universal time (UTC) format and reflect the time on the server.

Envelope information

Envelopes are headers and sometimes footers that are used to prefix or encapsulate documents that are transported. An envelope header contains information about the document or documents that it contains and how to route them. An envelope header contains the source organization identifier, destination organization identifier, and information about the type of document or documents that it contains.

BizTalk Server 2002 is capable of receiving and processing interchanges that contain multiple documents and groups of documents. When transporting documents that use an envelope, BizTalk Server includes each document in a separate interchange.

Envelopes are optional; however, if you choose to use an envelope, the format of an envelope that you specify in a messaging port must agree with the format of the document or documents that it contains. The document format is determined by the specification referred to in the outbound document definition of an associated channel. For example, if you choose an envelope with an X12 format for a messaging port, you must select an outbound document definition for the channel that points to an X12 specification. Conversely, if you select an outbound document definition in a channel, the messaging port that the channel is associated with must have an envelope with a matching format. For example, if you select an outbound document definition that has a specification with an X12 format, you should specify an X12 envelope in the messaging port.

Security properties

The security properties that you designate for a messaging port apply to all channels associated with that messaging port. For example, if you designate Secure Multipurpose Internet Mail Extensions (S/MIME) encryption for a messaging port, all documents processed by channels associated with that messaging port are encrypted using the specified encryption.

If you have documents that need to be secured using a different encryption or that do not need to be encrypted, you need to create a separate messaging port with the appropriate security properties for those documents.

BizTalk Server 2002 supports Multipurpose Internet Mail Extensions (MIME) encoding.

The MIME message format standard specifies how to format messages so that client programs can decode and display complex message bodies that can contain rich text, multiple character sets, and binary attachments such as pictures, sounds, and spreadsheets. MIME is a richer and more flexible technology than uuencode and provides generic and flexible mechanisms for including content within messages. With MIME formatting, you can:

  • Specify alternate content encoding mechanisms for each body part.

  • Relate groups of multiple content parts within a message.

  • Use character sets other than US-ASCII character sets in body parts and message header fields.

  • Specify the intended disposition of a content part (for example, inline or attachment).

BizTalk Server 2002 supports Secure Multipurpose Internet Mail Extensions (S/MIME) certificate-based public key encryption.

Encryption can be applied to business data that you send to your trading partners. By using an encryption certificate to secure the data, you can ensure that only the intended recipient can access the information.

To encrypt business data, the source organization must have a copy of the public key for the encryption certificate of the destination organization. The source organization uses this public key certificate to encrypt the business data and then forwards the encrypted data to the destination organization. The destination organization can then use the private key of its encryption certificate to decrypt the business data.

For an open messaging port, the encryption security properties are disabled because the destination organization is unknown.

BizTalk Server 2002 supports Secure Multipurpose Internet Mail Extensions (S/MIME) certificate-based public-key digital signing. For more information about certificates, see Understanding Certificates.

Digital signing can be used to ensure the authenticity of the source of data, to ensure that the data has not been modified, and to prevent the source of the data from repudiating the message.

A signature certificate is used to create digital signatures for authenticating data. Signing data does not alter the data, but it generates a digital signature string that is either bundled with the data or transmitted separately.

To digitally sign a document, the data is processed to create a message digest, which is a condensed text string that has been derived from a message. The source organization's private key is then used to encrypt the message digest to form the digital signature. The data, along with the digital signature, is transmitted to the recipient.

To verify a digital signature, the recipient must have a copy of the public key from the sender's signature certificate. The recipient decrypts the digest from the signature that was sent, and then calculates a message digest independently. The results of the two digests are compared; if they are identical, the information has not been tampered with.

Notes

  • If you submit MIME-encoded data using SMTP, a system-generated file name will appear in the main body of the output message, and your data will be displayed as an attachment.

  • For more information about certificates, see Certificates Overview.

Related Topics

Create and Manage Messaging Ports

Open Messaging Ports

Understanding Messaging Ports


Open Messaging Ports

An open messaging port is a messaging port to an organization for which you have not explicitly declared a specific destination organization. An open messaging port cannot have an application as its destination.

For an open messaging port, the destination and transport information must be provided either in the document or in parameters when the document is submitted to Microsoft BizTalk Server 2002. If submission parameters are used, they override any destination and transport information contained in the document. For more information about submitting documents, see Submitting.

When you create a channel for an open messaging port, and the destination information is provided in the document, the inbound document definition for that channel must reference a specification that is properly configured. For more information about how to configure a document specification to process documents for an open messaging port, see Set dictionary properties.

For an open messaging port, the encryption security properties are disabled because the destination organization is unknown. To set the encryption properties, you need to specify a certificate from a specific, known destination organization. An encryption certificate is used to encrypt documents that are transported to the specific destination organization.

You can use an open messaging port to send one or more standardized documents to many different current or future trading partner organizations without creating a messaging port for each destination. All documents share the same envelope, security, and transport properties that are established in the messaging port.

An open messaging port differs from a distribution list in the following ways:

  • With an open messaging port, each document from a channel results in only one document being delivered to only one destination. With a distribution list, each document from a channel can result in the document being delivered to multiple destinations.

  • With an open messaging port, you do not have to change the properties of the messaging port to send information to a different trading partner organization. With a distribution list, you have to add a messaging port to send information to a different trading partner organization.

Important

  • When you declare a messaging port as an open messaging port, you should not create channels for the messaging port that have an outbound document definition with an X12 or EDIFACT specification. To build an X12 or EDIFACT envelope, the server must have a source and a destination organization identifier. An open messaging port does not specify a destination organization identifier. In addition, the documents for an open messaging port must have the destination address within the document, but X12 and EDIFACT documents do not contain this information.

Related Topics

Create and Manage Messaging Ports

Messaging Port Elements

Understanding Messaging Ports


Understanding Organizations

The organizations that you create by using BizTalk Messaging Manager represent the trading partners with which you exchange documents. A special organization type, called the home organization, represents your business.

Home organization

BizTalk Messaging Manager creates the home organization for you automatically. When you configure the home organization, you can rename it to make it easier to identify as your business. There is only one home organization, and you cannot delete it.

You cannot designate the home organization as a source or destination for documents in a messaging port or a channel. Only applications of the home organization can be designated as the source or destination for documents within your business. For example, you might create a messaging port that designates a trading partner organization as the destination for documents that your business sends. Then, when you create a channel for that messaging port, rather than designating your home organization as the source, you would designate a specific internal application within your business where the documents originate. You also can designate one application of the home organization as the source for documents in a channel and another application as the destination in a messaging port.

Applications of the home organization

The applications that you add to the home organization enable you to identify and track the flow of documents between Microsoft BizTalk Server 2002 and actual internal applications within your business. However, simply creating an application and designating it as a source or destination within BizTalk Messaging Manager does not control or enable the flow of documents to or from an actual internal application. To integrate an internal application with BizTalk Server 2002 and direct the flow of documents to or from the application, you need to further configure the server.

There are several ways to transport documents from an originating application to BizTalk Server. The configuration needed to integrate an application to transport documents to the server is performed entirely outside BizTalk Messaging Manager. For more information, see Submitting.

To deliver documents from BizTalk Server to an internal application can require configuration both within and outside BizTalk Messaging Manager. The transport type and address that you specify in a messaging port can determine a specific location to which documents are delivered. An application or a separate component must then be configured to retrieve documents received at that location for the destination application. Or, within the transport properties of a messaging port, you can specify an application integration component that is capable of delivering documents directly to an application. For more information, see Understanding Messaging Ports.

Trading partner organizations

All other organizations that you create with BizTalk Messaging Manager represent external trading partners or business units of a trading partner. You can create any number of organizations. You can designate a trading partner organization either as a source of documents in a channel or a destination for documents in a messaging port.

You also can designate one trading partner as the source of documents in a channel and another as the destination for the documents in a messaging port. In this case, your business serves as a third-party intermediary between the two trading partners.

As with applications, simply creating an organization and designating it as a source or destination within BizTalk Messaging Manager does not enable the flow of documents to or from that organization. To control and direct the flow of documents between your partner organizations and BizTalk Server 2002, you need to further configure the server.

There are several ways for an external trading partner as a source organization to transport documents to your BizTalk Server. The configuration needed to do this is similar to the way that you integrate applications to transport documents to the server, and it is also performed entirely outside BizTalk Messaging Manager. For more information, see Submitting.

To deliver documents from your BizTalk Server to an external trading partner as a destination organization can require configuration both within and outside BizTalk Messaging Manager. The transport type and address that you specify in a messaging port determine a specific location to which documents are delivered. The destination organization, which must have access to this location, can then configure its own BizTalk Server, one of its internal applications, or a separate component to process the documents received at that location. For more information about configuring messaging ports, see Understanding Messaging Ports.

The following topic is covered in this section:

  • 3Organization Identifiers


Organization Identifiers

Microsoft BizTalk Server 2002 and other trading partners use organization identifiers to uniquely identify organizations. An organization can have more than one organization identifier; however, each identifier must be unique to that organization. For example, a telephone number, a URL, or a Data Universal Numbering System (D-U-N-S) number can each uniquely identify an organization, but no two organizations can use the same telephone number as an organization identifier.

An organization identifier consists of three separate elements: a name, a qualifier, and a value. For example, a business might use a telephone number to uniquely identify itself. In this example, the name of the identifier is "telephone number," the qualifier that identifies the identifier as a telephone number is the number 12, and the value of the actual telephone number is (801-555-1079). Each organization identifier name has a unique qualifier that is used in place of the name to indicate the type of identifier. For example, the standard qualifier for a telephone number identifier is 12. When BizTalk Server 2002 processes documents, only the qualifier and the value are used to identify organizations.

Each organization must have at least one identifier. When you create an organization, BizTalk Messaging Manager creates an identifier with the name Organization. The qualifier for this identifier is OrganizationName, and its value is the name that you give to the organization. This identifier is also set as the default identifier, which means that it is used when no other identifier is specified. You can create additional identifiers and designate any identifier as the default identifier. You cannot delete the OrganizationName identifier or the designated default identifier. The default identifier is used to identify an organization unless you override it by selecting a different identifier in a messaging port or channel.

When BizTalk Server 2002 processes and transports a document, it includes the organization identifiers of the destination organization and the source organization in the envelope header. When BizTalk Server 2002 receives documents, it searches the data for the source organization and the destination organization identifiers. The server then uses the identifiers and the document-definition name to determine which channels to use to process the documents.

Interchanges with an EDI format have restrictions on organization identifiers. When you use an organization identifier for X12 envelopes, you should not use the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 2 characters or a value that exceeds 15 characters. When you use an organization identifier for EDIFACT envelopes, you should not use the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 4 characters or a value that exceeds 35 characters.

Notes

  • If the server encounters an empty qualifier and a non-empty value when processing an inbound document with an EDIFACT format, it converts the empty qualifier to a dash (-). If you want to process an inbound document with an EDIFACT format that has an empty qualifier, or an outbound envelope with an empty qualifier, you must create a custom organization identifier that has a single dash as the qualifier. For an outbound EDIFACT document, the server converts the dash to an empty qualifier.

  • If the server encounters an empty qualifier and a non-empty value when processing an inbound document with a format other than EDIFACT, it converts the empty qualifier to OrganizationName.

Related Topics

Create and Manage Organizations

Understanding Organizations


Understanding Document Definitions

A document definition represents a specific type of document that is processed by Microsoft BizTalk Server 2002. A document definition represents the type of inbound or outbound document in a channel and provides a pointer to a document specification. The document specification defines the document structure, type, and version. The same document specification can be used in any number of document definitions, and the same document definition can be used in any number of channels.

If the format and structure of the inbound and outbound document in a channel are the same, you can use the same specification for both. Otherwise, you must specify a map, which the server uses to transform the format or structure of the inbound document into that of the outbound document.

When BizTalk Server 2002 receives a document, it identifies the appropriate channel or channels that have matching inbound document definitions. The inbound document definition for each channel points to a specification. The server uses the specification to translate a non-XML inbound document from its original format into an intermediate XML format, and to validate the document's structure. The outbound document definition for the channel also points to a specification. The server uses the outbound document specification to validate the data structure of the outbound document. If required, the server also can use the specification to translate the outbound document from an XML format into a format that the destination organization or destination application can recognize and use. The destination is designated in the messaging port with which the channel is associated.

A document specification for a document definition is optional; however, in most cases you should select one. If you do not select a specification:

  • The data that you process is not translated into XML on the inbound side or from XML on the outbound side.

  • The data is not validated against a specification to ensure that it does not contain errors.

  • You cannot transform the structure or format of the data by using a map in a channel.

  • You cannot specify global tracking fields or selection criteria.

A document specification is not required if you want to use the document definition in a pass-through submission for data that is not in Unicode XML format. An example would be if you want to send binary data through BizTalk Server 2002 to a destination without transforming the data in any way. In this case, you should not select a document specification for either the inbound or the outbound document definition of the channel that is used for the pass-through submission.

The following topics are covered in this section:

  • Tracking Document Data Fields

  • Understanding Selection Criteria

Related Topics

Create and Manage Document Definitions

Using BizTalk Editor

Mapping Specifications

Understanding Channels


Tracking Document Data Fields

In a document definition, you can designate fields contained within the specification that you want to log to a Tracking database. The fields that you designate in a document definition are tracked for all document instances processed by channels that use the document definition as its inbound document definition. Because these fields are tracked for all channels, they are referred to as global tracking fields.

When you select an inbound document definition for a channel, you can designate specification fields from within the channel to be tracked. The specification fields that you designate in a channel are tracked in place of any global tracking fields for documents that are processed by that specific channel.

The fields that you designate for tracking in a document definition or in a channel are logged to a Tracking database only for the inbound document definition of the channel. Any fields that are designated for tracking in the outbound document definition of the channel are not tracked.

With the tracking data from the documents that are processed, you can analyze information about your operation. For example, an invoice-total field can be tracked for every invoice that you send to your trading partners. You can then determine the total dollar amount for invoices sent to all trading partners for a given period of time, or you can determine the total dollar amount of invoices for each individual trading partner.

Related Topics

Create and Manage Document Definitions

Using BizTalk Document Tracking


Understanding Selection Criteria

Selection criteria are a unique set of name-value pairs that Microsoft BizTalk Server 2002 uses only to process EDI documents. For inbound X12 or EDIFACT documents, the server uses selection criteria to uniquely identify and select a document definition because no document definition name is available within individual EDI documents.

For outbound X12 or EDIFACT documents, selection criteria are used to create the functional group header information in the envelope.

The following topics are covered in this section:

  • Using Selection Criteria with Inbound Documents

  • Using Selection Criteria with Outbound Documents


Using Selection Criteria with Inbound Documents

To process inbound documents, BizTalk Server 2002 must have the name of an inbound document definition. The server usually obtains the name of the inbound document definition from either a field within the incoming document or a parameter that is submitted along with the document. For more information, see Submitting.

For X12 and EDIFACT inbound interchanges, the documents can be contained within the functional group or interchange headers. BizTalk Server 2002 processes the documents contained in these groups and interchanges individually. Because the document-related information for each document is contained in the functional group or interchange header, the server cannot obtain a document definition name from within the individual documents. Also, since an interchange can contain multiple groups with different types of documents, a single document definition name cannot be provided as a submission parameter for the server for identifying a document definition.

In such cases, BizTalk Server 2002 is able to extract document-related data from the functional group header (the GS header of an X12 interchange and the UNG header of an EDIFACT interchange) or the interchange header in an EDIFACT interchange without functional groups. By matching the values of this data to the values of selection criteria specified in a document definition, the server can uniquely identify the appropriate document definition.

For BizTalk Server 2002 to match the selection criteria values to the corresponding header elements of an inbound interchange, you must type the selection criteria names exactly as shown in the following tables.

X12 header elements

Name | Requirement | GS element
functional_identifier | Mandatory | GS01
application_sender_code | Mandatory | GS02
application_receiver_code | Mandatory | GS03
standards_version | Mandatory | GS08

EDIFACT header elements

Name | Requirement | UNH element | UNG element
functional_identifier | Mandatory | S009, 0065 | 0038
application_sender_code | Optional | Not used | S006, 0040
application_receiver_code | Optional | Not used | S007, 0044
standards_version_type | Mandatory | S009, 0052 | S008, 0052
standards_version_value | Mandatory | S009, 0054 | S008, 0054

Related Topics

Create and Manage Document Definitions

Understanding Selection Criteria

Using Selection Criteria with Outbound Documents


Using Selection Criteria with Outbound Documents

To process an outbound X12 or EDIFACT document, BizTalk Server 2002 places each document into a valid envelope of the appropriate format. To create the envelope, the server inserts the value data of the selection criteria into the corresponding fields of the group and message headers. To build the headers, the server uses the selection criteria values contained in the outbound document definition for the channel.

For example, suppose that you create a document definition that has the name-value pair of functional_identifier/ORDERS as one of its selection criteria. If you then use this as the outbound document definition in a channel, the value of the group header field that corresponds with the selection criteria named functional_identifier is set to ORDERS in the envelope header.

For BizTalk Server 2002 to insert selection criteria values to the corresponding header elements, you must type the selection criteria names exactly as shown in the following tables.

X12 header elements

Name | Requirement | GS element
functional_identifier | Mandatory | GS01
application_sender_code | Mandatory | GS02
application_receiver_code | Mandatory | GS03
standards_version | Mandatory | GS08

EDIFACT header elements

Name | Requirement | UNH element | UNG element
functional_identifier | Mandatory | S009, 0065 | 0038
application_sender_code | Optional | Not used | S006, 0040
application_receiver_code | Optional | Not used | S007, 0044
standards_version_type | Mandatory | S009, 0052 | S008, 0052
standards_version_value | Mandatory | S009, 0054 | S008, 0054

Related Topics

Create and Manage Document Definitions

Understanding Selection Criteria

Using Selection Criteria with Inbound Documents


Understanding Envelopes

An envelope encapsulates electronic business data for transport. An envelope typically consists of header and footer information, or of header information only. The envelope properties that you specify provide Microsoft BizTalk Server 2002 with information that the server needs to either open inbound interchanges or create outbound interchanges. When you create an envelope, you specify an envelope format; for certain types of formats, you also can select an envelope specification.

The envelope formats supported by BizTalk Server 2002 are custom XML, ANSI X12, EDIFACT, flat file (delimited and positional), custom, and reliable. The reliable format processes envelopes that are compliant with BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/). If you specify a custom envelope format, you must create and register a custom parser component to process inbound envelopes or a custom serializer component to process outbound envelopes. For more information, see Parsers and Serializers.

Custom XML and flat-file formats

To enable BizTalk Server 2002 to process inbound interchanges with a custom XML or flat-file format, you must create envelopes with a matching format. To enable BizTalk Server to process inbound interchanges with a custom format, you must create and register a custom parser component. BizTalk Server can process inbound interchanges with ANSI X12, UN/EDIFACT, or reliable formats without using an envelope created by using BizTalk Messaging Manager.

To process outbound documents with any format, you must create an envelope and select it in a messaging port to create an interchange with the required envelope format and header information. BizTalk Server places only one document in each outbound interchange.

X12 and EDIFACT formats

When you select an envelope with an X12 or EDIFACT format in a messaging port, you must also specify delimiters and an interchange control number. These EDI properties apply only to the envelopes selected for use with that messaging port. When you select an envelope with a custom format, delimiters and an interchange control number are optional and depend on the requirements of your custom parser or serializer components. When you create a channel for a messaging port that uses an X12, EDIFACT, or custom envelope, you can specify a functional group control number that applies only to documents processed by that channel and messaging port combination.

The format of an envelope that you select in a messaging port must agree with the format of the outbound document that it contains. The format of the outbound document is determined by the specification referred to in the outbound document definition of a channel. For example, if you choose an envelope with an X12 format for a messaging port, when you create a channel for that messaging port you must select an outbound document definition that points to a specification that also has an X12 format.

If you do not specify an envelope when creating a messaging port, the data is sent in XML format without any header.

Handling DBCS characters

International Issue

The UNOX syntax identifier in EDIFACT is defined as a code extension technique to cover other non-single-byte characters. However, some countries had already defined their own standards before the UNOX syntax was created. For example, in Korea, the standard called KEDIFACT marks data by KECA rather than UNO*. (The UNO* syntax is specified in ISO 9735 EDIFACT System Rules.) The EDIFACT data received by BizTalk Server has a modified header such that it is UNOA; however, the double-byte character set (DBCS) characters still remain. UNOA consists of uppercase ASCII characters only, and does not properly convert the DBCS characters.

To resolve this, the EDIFACT parser and serializer have been updated. If the header is in UNOA characters, the EDIFACT parser and serializer accept a registry key to define a codepage, other than the default codepage, that converts the data. A registry value, called EDIFACTUNOACodepage, has been added to the set of values that BizTalk Server defines. This registry value has a default of 0, and, if set to 0, uses BizTalk Server behavior. If this registry value is set to another value, that value is the codepage value used to convert the resultant KEDIFACT data.

The codepage change is global. All EDIFACT data passing through BizTalk Server processes data according to the EDIFACTUNOACodepage codepage.

Important

  • EDIFACT documents with the UNOX or the UNOY syntax identifier are not supported in BizTalk Server 2002.

Notes

  • A control number can be skipped if a catastrophic failure occurs after a document has been sent but before it has been removed from the BizTalk Server Work queue. To avoid serialization of all threads, the control number from the BizTalk Server database is retrieved and incremented outside of the COM+ transaction but within its own local SQL transaction. Therefore, while a control number will be used only once, it is possible that a thread that received control number 1000 would fail after retrieving this number. In this case, if the transport was transacted, the transmission is rolled back. If the transaction did not take place, the message might not yet have been sent at the moment of failure. In either case, the control number associated with that document is skipped and not reused.

  • When processing envelopes that are compliant with BizTalk Framework 2.0, BizTalk Server 2002 should be considered the endpoint with regard to the expiration time. When BizTalk Framework 2.0–compliant documents are submitted to BizTalk Server 2002, either from an application or a trading partner, the following fields are overwritten if present, or created if absent:
    • In the properties subsection:

      <prop:identity>

      <prop:sentAt>

      <prop:expiresAt>

    • In the receipt information subsection:

      <sendTo>

      <address>

      <sendReceiptBy>

The following topics are covered in this section:

  • Using Envelopes for Inbound Processing

  • Using Envelopes for Outbound Processing

Related Topics

Create and Manage Envelopes

Understanding Messaging Ports


Using Envelopes for Inbound Processing

Microsoft BizTalk Server 2002 can process an inbound interchange with an X12 or EDIFACT format without using an envelope created by using BizTalk Messaging Manager.

For BizTalk Server 2002 to process an inbound interchange with a flat-file format, you must create an envelope by using BizTalk Messaging Manager. That envelope must point to a specification that the server can use to interpret and open the interchange. The name of the envelope must be provided to the server when the interchange is submitted for processing. For more information, see Submitting.

For BizTalk Server 2002 to process an inbound interchange with a custom XML format, you must create an envelope by using BizTalk Messaging Manager. However, the server is able to locate the custom XML envelope that it needs to interpret and open the interchange without the name of the envelope being provided at submission. You can provide the server with the name of the envelope at submission, but it is not required. For more information, see Submitting.

For BizTalk Server 2002 to process an inbound interchange with a custom format, you must create a custom parser to open the interchange. For more information, see Parsers.

The envelopes that you create to process inbound interchanges do not need to be selected in a messaging port to be used by the server. Only envelopes used for processing outbound interchanges need to be selected in a messaging port.

Related Topics

Create and Manage Envelopes

Understanding Envelopes

Using Envelopes for Outbound Processing


Using Envelopes for Outbound Processing

Messaging ports regulate the outbound flow of data from Microsoft BizTalk Server 2002 to a specified destination. When you create a messaging port, you can select an envelope for the documents that are processed by that messaging port. If you select an envelope, the envelope format must match the format of the documents that the envelope contains. The format of the documents is determined by the specification referred to in the outbound document definition of a channel. Once you create an envelope by using BizTalk Messaging Manager, you can use it in any number of messaging ports.

When BizTalk Server 2002 processes an outbound document, the server uses the properties of the envelope selected in the messaging port to create an interchange by encapsulating or prefixing the document. If you do not specify an envelope for a messaging port, the data is sent in XML format without any header or footer. If you specify a custom XML format, but do not select an envelope specification, the data is sent using the reliable format. The reliable format processes envelopes that are compliant with BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/).

For BizTalk Server 2002 to process an outbound interchange with a custom format, you must create a custom serializer to create the interchange. For more information, see Serializers.

When you select an envelope with an X12 or EDIFACT format, you must specify an interchange control number and delimiters. An interchange control number is used to identify and track documents that are processed using the messaging port. The interchange control number is incremented with each use of the envelope and messaging port. Delimiters indicate the characters that are used to separate the records and fields of the envelope and the documents contained in the envelope. For envelopes with a custom format, an interchange control number and delimiters are optional.

Important

  • The envelope format for a messaging port must agree with the document type format of the specification that is referred to by the outbound document definition for any associated channel. For example, if you choose an envelope with an X12 format for a messaging port, you must select an outbound document definition for the channel that points to an X12 specification.

Related Topics

Create and Manage Envelopes

Understanding Envelopes

Using Envelopes for Inbound Processing


Understanding Receipts

When exchanging documents with a trading partner, your business processes might require you to receive receipts for the documents that you send, or to generate receipts for documents that a trading partner sends to your business.

BizTalk Messaging Services provides two methods for processing receipts for interchanges. For interchanges that use the X12 or EDIFACT parser, or a custom parser that requires receipts, you can configure BizTalk Messaging Manager to use channel properties to process receipts. For interchanges that use the XML parser, you have the option of using reliable messaging, which processes receipts automatically to guarantee the reliable delivery of data.

The following topics are covered in this section:

  • Processing Receipts Using Channels

  • Processing Receipts Using Reliable Messaging


Processing Receipts Using Channels

This section explains how you can configure BizTalk Messaging Services to use channel properties to control the processing of receipts. The destination system is configured to generate (send) receipts to the source system. The source system is configured to expect (receive) receipts from the destination system and correlate them with the original interchanges. This configuration applies only if you process interchanges that use the X12 or EDIFACT parser, or a custom parser that requires receipts. For more information about creating custom parsers, see Parsers. If you process interchanges that use the XML parser, see Processing Receipts Using Reliable Messaging.

If you use a custom parser and want to correlate receipts with the original interchanges, you must create a custom correlation component.

For the source system to receive receipts, the destination system also must be configured to send receipts. Configuring a channel on the source system to expect a receipt is not sufficient to receive receipts.

The following illustration shows the configuration for both the source and destination systems using channel properties for processing receipts.

Processing receipts using channels

The following topics are covered in this section:

  • Configuring the Source System for Channel Receipts

  • Configuring the Destination System for Channel Receipts


Configuring the Source System for Channel Receipts

This topic explains how to configure BizTalk Messaging Services to send an interchange to a trading partner and to process a receipt by using channel properties.

You must create a channel and a messaging port to process and transport an interchange to the destination system. You do not need to create a channel and messaging port to process the receipt that the destination system returns. However, you must create a document definition that the server uses to validate the receipt when it is returned.

To configure BizTalk Messaging Services to send an interchange to a destination system and to process a receipt by using channel properties, perform the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications for the inbound and outbound document definitions for the original document for the interchange. You also must create a specification for the document definition that the server uses to validate the receipt when it is received.
  • Create and Validate Specifications

    Notes

    • For the outbound document definition for the channel, you must create a specification that uses the format required by the destination system. For example, X12.

    When BizTalk Messaging Services on the destination system processes the interchange, and the parser requires receipts, the parser does the following:

    • Extracts header elements from the interchange.

    • Generates a canonical receipt.

    • Inserts the elements into the canonical receipt.

    For the source system, the specification for the outbound document definition of the channel used to process the interchange also must contain these fields. And, the specification for the document definition to validate the receipt must contain these fields. The source system uses these elements to correlate the receipt with the original interchange.

    The X12 header elements are:

    • functional_identifier

    • standards_version

    The EDIFACT header elements are:

    • functional_identifier

    • standards_version_type

    • standards_version_value
Using BizTalk Messaging Manager:
  • Create the inbound and outbound document definitions for creating the channel and a document definition for the receipt.
  • Create document definitions

    Notes

    • In the document definitions, you must select the specifications that you created previously. For more information, see Select a document specification.

    • You also must create a document definition for the receipt.
  • Create a messaging port for transporting the receipt to the source system.
  • Create messaging ports

    Note

    • You must create the messaging port and its associated receipt channel for processing the receipt first. When you create the channel for processing the original interchange, you must specify the receipt channel.
  • Create a messaging port for transporting the interchange to the destination system.
  • Create messaging ports
  • Create a channel to process the original interchange from your trading partner.
  • Create channels

    Notes

    • On the Source Application or Source Organization page of the Channel Wizard, select the Expect receipt check box.

    • In the Expect receipt area, in the Receipt interval in minutes box, set the time that you want to wait to receive the receipt before resending the original interchange. For more information, see Set source application properties or Set source organization properties.
Using BizTalk Document Tracking:
  • The original interchange is logged to the Tracking database and the receipt status field (nACKStatus) is set to "Pending". The receipt status in the Tracking database subsequently changes to reflect the status of the receipt process.
  • Understanding Document-Instance Record Results

  • Understanding Receipt Results

Submitting receipts on the source system

Receipts are submitted to BizTalk Messaging Services in the same manner as other documents. Once a receipt is submitted, the X12 and EDIFACT parsers can distinguish a receipt from other documents and direct the server to correlate the receipt with the original interchange.

Important

  • Receipts must be submitted to BizTalk Messaging Services without using any submission parameters.


Configuring the Destination System for Channel Receipts

This topic explains how to configure BizTalk Messaging Services to process an interchange from a trading partner and to generate a receipt by using channel properties. To do this, you must create a channel and a messaging port to process the outbound interchange and transport it to the destination system. You do not need to create a channel or a messaging port to process the receipt that the destination system returns. A parser processes the receipt by using only a document definition.

To configure BizTalk Messaging Services to process an interchange from the source system and to send a receipt by using channel properties, perform the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications for the inbound and outbound document definitions that are used to create the receipt channel.
  • Create and Validate Specifications

    Notes

    • For the inbound document definition of the receipt channel, you use the Canonical Receipt specification. This specification is located in the WebDAV repository.

    • For the outbound document definition of the receipt channel, you must create a specification that uses the format required by your business process.

    When BizTalk Messaging Services on the destination system processes an inbound interchange, and the parser requires receipts, the parser does the following:

    • Extracts group header elements.

    • Generates a canonical receipt.

    • Inserts the header elements into the canonical receipt.

    The outbound document specification for the receipt channel must contain fields for these header elements. The source system uses the header elements to correlate the receipt with the original interchange.

    The X12 header elements are:

    • functional_identifier

    • standards_version

    The EDIFACT header elements are:

    • functional_identifier

    • standards_version_type

    • standards_version_value
  • Create the specifications for the inbound and outbound document definitions that are used to create the channel to process the original interchange from the source system.
  • Create and Validate Specifications
Using BizTalk Mapper:
  • Create a map for the receipt channel.
  • Create new maps

    Notes

    • When you create the receipt channel, you must specify a map. The map is used to transform the canonical receipt into the correct document type for the outbound document.

    • You can use one of the maps provided with BizTalk Server 2002, if it matches the document type that is required for your business process. You can retrieve these maps from the WebDAV repository.

      –Or–

      You can create your own map using the Canonical Receipt specification and a specification that matches the document type required for your business process.
Using BizTalk Messaging Manager:
  • Create the document definitions for the receipt channel and for the channel that you use to process the original interchange.
  • Create document definitions

    Notes

    • In the document definitions, you must select the specifications that you created previously. For more information, see Select a document specification.

    • You also must create the document definitions for the channel that is used to process the original interchange. The configuration for these varies depending on your business process.
  • Create a messaging port for transporting the receipt to the source system.
  • Create messaging ports

    Note

    • You must create the messaging port and its associated receipt channel for processing the receipt before you create those that are used for the original interchange. When you create the channel for processing the original interchange, you must specify the receipt channel.
  • Create a receipt channel from an application for processing the receipt.
  • Create channels

    Notes

    • On the General Information page of the Channel Wizard, select the This is a receipt channel check box.

    • On the Source Application page of the Channel Wizard, in the Name list, select an application.

      You can create an application for the home organization that you use to designate receipts that are generated by the parsers.

    • On the Inbound Document page of the Channel Wizard, click Browse and browse to the document definition that you created earlier and that uses the Canonical Receipt specification.

    • On the Outbound Document page of the Channel Wizard, click Browse and browse to the document definition that you created earlier and that uses the specification with the document type required for your business process.
  • Create a messaging port for transporting the documents contained in the original interchange to their intended destination.
  • Create messaging ports

    Note

    • This messaging port does not require special configuration for processing receipts.
  • Create a channel to process the original interchange from your trading partner.
  • Create channels

    Notes

    • On the Source Organization page of the Channel Wizard, select the Generate receipt check box.

    • In the Generate receipt area, click Browse and select the receipt channel that you created to process the receipt. For more information, see Set source organization properties.

    • On the Advanced Configuration page of the Channel Wizard, in the Retry options area, you can set the number of retries and the interval. For more information, see Set advanced configuration properties.
Using BizTalk Document Tracking:
  • The original interchange and the receipt are logged to the Tracking database.
  • Understanding Document-Instance Record Results

  • Understanding Receipt Results


Processing Receipts Using Reliable Messaging

This section explains how you can configure BizTalk Messaging Services to send and receive receipts by using reliable messaging envelopes, which create interchanges that are compliant with BizTalk Framework 2.0. Reliable messaging enables receipts to be processed automatically, to ensure the reliable delivery of data. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/). If you send and receive interchanges that use the X12, EDIFACT, or a custom parser, see Processing Receipts Using Channels.

By using BizTalk Messaging Manager, you can configure a messaging port to use a reliable envelope format for an outbound interchange. Envelopes that use the reliable messaging format must always include a reply-to URL address in the header. The reply-to address is used by the destination system to send a receipt to the interchange sender system.

The following topics are covered in this section:

  • Configuring the Source System for Reliable Messaging Receipts

  • Configuring the Destination System for Reliable Messaging Receipts


Configuring the Source System for Reliable Messaging Receipts

To configure BizTalk Messaging Services to send an interchange to a destination system and to process a receipt by using reliable messaging, perform the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Server Administration:
  • Configure the reliable messaging reply-to address property.
  • Configure general properties for a server group.

    Notes

    • In BizTalk Server Administration, expand Microsoft BizTalk Server 2002 and click the server group that you want to configure.

    • On the Action menu, click Properties.

    • In the BizTalk Server Group Properties dialog box, in the Reliable messaging reply-to URL box, type the URL that this server group uses to receive reliable messaging delivery receipts.

      When you create an outbound interchange that uses a reliable messaging envelope, the server automatically inserts the Reliable messaging reply-to URL into the header of the outbound interchange. The server also places the original interchange into the Retry queue. The server uses the Retry options specified in the channel to determine the number of times to resend the original interchange until a receipt has been received.
Using BizTalk Messaging Manager:
  • Create an envelope that uses the reliable envelope format.
  • Create envelopes

    Note

    • In the New Envelope dialog box, in the Envelope format list, click RELIABLE.
  • Create a messaging port for transporting the original interchange to the destination system.
  • Create messaging ports

    Note

    • On the Envelope Information page of the New Messaging Port Wizard, in the Envelope information area, select the envelope that you created previously. For more information, see Set envelope information properties.
  • Create a channel to process the original interchange.
  • Create channels

    Notes

    • On the Source Application or Source Organization page of the Channel Wizard, do not set any receipt properties.

    • On the Advanced Configuration page of the Channel Wizard, in the Retry options area, you can set the number of retries and the interval. For more information, see Set advanced configuration properties.
Using BizTalk Document Tracking:
  • On the source system, the original, outbound interchange is logged to the Tracking database; however, the receipt that is returned is not.
  • Understanding Document-Instance Record Results

  • Understanding Receipt Results


Configuring the Destination System for Reliable Messaging Receipts

When BizTalk Messaging Services for the destination system receives an interchange with a reliable messaging format, it uses a special document definition, channel, and messaging port to process and transport a receipt to the source system. These special system objects are not viewable in BizTalk Messaging Manager, and you cannot create similar objects using the reserved system names.

The server uses the reply-to address that is included in the header of the inbound interchange as the destination address for the receipt.

You do not need to further configure BizTalk Messaging Services for the destination system to return a receipt for an interchange that is sent with a reliable messaging envelope, except when the source system specifies an SMTP address as the reliable messaging reply-to URL address. To send receipts to an SMTP address, your server must be configured to include a From address in the header of the receipt.

When BizTalk Server 2002 is installed, an organization identifier is created for the home organization. This identifier is named Reliable Messaging Acknowledgement SMTP From Address, and it cannot be removed. When sending a reliable messaging receipt to an SMTP address, the server inserts the value that you specify for this organization identifier into the interchange header as the From address.

To configure BizTalk Messaging Services to send a receipt to a source system using an SMTP reliable messaging reply-to address, perform the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Messaging Manager:
  • Configure the Reliable Messaging Acknowledgement SMTP From Address organization identifier of the home organization.
  • Configure the home organization

    Notes

    • Open the home organization.

    • In the Organization Properties dialog box, click the Identifiers tab.

    • 3In the Organization identifiers list, click Reliable Messaging Acknowledgement SMTP From Address and click Edit.

    • In the Identifier Properties dialog box, in the Value box, type a value for the identifier. For more information, see Edit organization identifiers.

    Important

    • Do not modify the name or qualifier for this identifier, but only modify the value.
  • Create a messaging port for transporting the original interchange to its intended destination.
  • Create messaging ports

    Note

    • This messaging port does not require special configuration.
  • Create a channel to process the original interchange.
  • Create channels

    Note

    • This messaging port does not require special configuration.
Using BizTalk Document Tracking:
  • On the destination system, the inbound interchange is logged to the Tracking database, but the receipt is not.
  • Understanding Document-Instance Record Results

  • Understanding Receipt Results


Understanding Distribution Lists

A distribution list is a group of messaging ports with which you can send the same document to several different trading partner organizations or internal applications.

You can use a distribution list to send the same data to several trading partner organizations or internal applications of your home organization at the same time. For example, you can send the same catalog, price list, or newsletter to several trading partner organizations by submitting the information only once to Microsoft BizTalk Server 2002.

You must first create a messaging port to each of the trading partner organizations or internal applications that you want to receive the data, and then add the messaging ports to a distribution list. Open messaging ports cannot be added to a distribution list. You can create new messaging ports to additional trading partner organizations or internal applications, and then add those messaging ports to an existing distribution list. For more information, see Create messaging ports.

You must create at least one channel for each distribution list, or else the distribution list is not functional. For more information, see Create channels.

When BizTalk Server 2002 invokes a channel related to a distribution list, it invokes only the channel that is associated with the distribution list to process the data. None of the channels that are associated with the individual messaging ports in the distribution list are invoked. The server uses the properties of each messaging port successively to transport the data to the destinations specified in the messaging ports.

A distribution list differs from an open messaging port in the following ways:

  • With a distribution list, each document from a channel can result in the document being delivered to multiple destinations. With an open messaging port, each document from a channel results in only one document being delivered to only one destination.

  • With a distribution list, you have to add a messaging port to send information to a different trading partner organization. With an open messaging port, you do not have to change the properties of the messaging port to send information to a different trading partner organization.

Related Topic

Use Distribution Lists


Why Perform BizTalk Messaging Manager Tasks

This section provides a quick reference about why you perform BizTalk Messaging Manager tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
Create and Manage Channels:
  • Create channels
 To process documents received through BizTalk Messaging Services.
  • Set Channel Properties
  • To designate specification fields to track for the inbound document definition.

  • To create a channel filtering expression, which determines if BizTalk Server invokes the channel, based on the value of a field or fields within the document being processed.

  • To configure receipts, security properties, and document logging options.

  • To specify a group control number for documents with electronic data interchange (EDI) formats, set the number and time interval that the server uses to resend documents, or override the transport component and envelope properties for the messaging port or distribution list.
Create and Manage Messaging Ports:
  • Create messaging ports
 To transport documents received through BizTalk Messaging Services to a specified destination.
  • Set Messaging Port Properties
  • To designate a specific address to which documents are delivered.

  • To set the transport type for getting documents to that location.

  • To specify how the documents are enveloped and secured prior to transport.
Create and Manage Organizations:
  • Configure the home organization
  • To change the name of your home organization from the name it was given by BizTalk Messaging Manager.

  • To modify the values of the home organization identifiers, which are properties used to uniquely identify the home organization.

  • To set application properties, which enable you to identify and track the flow of documents between BizTalk Server and internal applications within your business.
  • Create organizations
 To enable document exchange between your company and your trading partners. The home organization represents your company and is automatically created for you by BizTalk Messaging Manager. All other organizations that you create represent external trading partners or business units of a trading partner.
  • Set Organization Properties
  • To set organization identifiers, which are properties used to uniquely identify organizations.

  • To set application properties, which enable you to identify and track the flow of documents between your company and your trading partners.
Create and Manage Document Definitions:
  • Create document definitions
 To represent specific types of documents that are processed by BizTalk Server.
  • Set Document Definition Properties
  • To create a document specification, which defines a document's structure, type, and version. The same document specification can be used in any number of document definitions, and the same document definition can be used in any number of channels.

  • To set global tracking properties so you can track documents through the Tracking database.

  • To set selection criteria, which are a unique set of name-value pairs that BizTalk Server uses to process EDI documents.
Create and Manage Envelopes:
  • Create envelopes
 To encapsulate electronic business data for transport. The envelope properties that you specify provide BizTalk Server with information that the server needs to either open inbound interchanges or create outbound interchanges.
  • Select an envelope specification
 To apply a specification to an envelope format.
Use Distribution Lists:
  • Create distribution lists
 To send the same document to several different trading partner organizations or internal applications.


How to Perform BizTalk Messaging Manager Tasks

This section provides task-specific information about how to use BizTalk Messaging Manager. It is highly recommended that you review About BizTalk Messaging Manager to fully understand the relationships between objects that you can create by using BizTalk Messaging Manager.

The following topics are covered in this section:

  • Create and Manage Channels

  • Create and Manage Messaging Ports

  • Create and Manage Organizations

  • Create and Manage Document Definitions

  • Create and Manage Envelopes

  • Use Distribution Lists


Create and Manage Channels

This section provides task-specific information about how to create and manage channels. It is highly recommended that you review Understanding Channels to fully understand channels.

The following procedures are covered in this section:

  • Create channels

  • Search for channels

  • Edit channels

  • Delete channels

  • Set Channel Properties


Create channels

You must create a messaging port or a distribution list before you can create a channel. For more information, see Create messaging ports or Create distribution lists.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the Search for other items area, click Messaging ports or Distribution lists and click Search Now.

  3. In the Messaging Port Name list, click the messaging port for which you want to create a channel.

    –Or–

    In the Distribution List Name list, click the distribution list for which you want to create a channel.

  4. In BizTalk Messaging Manager, on the File menu, point to New, point to Channel, and then complete one of the following steps:
    • To create a channel from an organization, click From an Organization.

    • To create a channel from an application, click From an Application.

    The New Channel Wizard opens.

  5. On the General Information page, set the properties and click Next.

    For more information, see Set general channel-information properties.

  6. Complete one of the following steps:
    • If you are creating a channel from an organization, set the properties on the Source Organization page and click Next. For more information, see Set source organization properties.

    • If you are creating a channel from an application, set the properties on the Source Application page and click Next. For more information, see Set source application properties.
  7. On the Inbound Document page, set the properties and click Next.

    For more information, see Set inbound document properties.

  8. On the Outbound Document page, set the properties and click Next.

    For more information, see Set outbound document properties.

  9. On the Document Logging page, set the properties and click Next.

    For more information, see Set document logging properties.

  10. On the Advanced Configuration page, set the properties and click Finish.

    For more information, see Set advanced configuration properties.

  11. After you have set all channel properties, on the Advanced Configuration page click Finish to close the New Channel Wizard.

Notes

  • You cannot name a channel using the reserved system name, Reliable Message Acknowledgement Channel.

  • You can use this procedure to create either a standard channel or a receipt channel. The procedures in this section contain notes that explain which channel properties are not available when you are creating a receipt channel.

  • If you create a messaging port and a channel to use for a pass-through submission of data, you can use only the service window and the retry count and interval features of the channel, and the transport features of its associated messaging port. You cannot use the verification of decoding or decryption, filtering, document tracking, or mapping features of the channel.

  • When you save a channel that references a map that is outside your local network that is protected by an Internet firewall, you might receive an error due to the firewall configuration. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Delete channels

Edit channels

Search for channels

Set Channel Properties

Understanding Channels


Search for channels

  1. In BizTalk Messaging Manager, in the Search for other items area, click Channels.

  2. To search for all channels, clear all search criteria and click Search Now.

  3. Do one or more of the following:
    • To search for channels with a specific name, in the Search for channels area, in the Channel name box, type the name of the channel that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for channels from a specific type of source, in the Source list, click a source type and click Search Now.

    • To search for channels associated with a specific messaging port or distribution list, in the Associated with messaging port or distribution list box, type the name of a messaging port or distribution list and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for channels that use a specific document definition, in the Using document definition box, type the name of a document definition and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

Notes

  • You can set more than one search criteria before clicking Search Now.

  • To clear the search criteria and search results, click Clear Search.

  • You can also search for channels associated with a specific messaging port or distribution list by right-clicking the messaging port or distribution list and clicking Find Channels.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • You can use the following wildcard characters in the search criteria.
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Delete channels

Edit channels

Set Channel Properties

Understanding Channels


Edit channels

  1. In BizTalk Messaging Manager, in the Channel Name list, click the channel that you want to edit.

    For information about searching for channels, see Search for channels.

  2. On the File menu, click Edit.

    The Channel Properties Wizard opens.

  3. On the General Information page, edit the appropriate properties.

    For more information, see Set general channel-information properties.

    After editing the properties on any page, you can click Finish to close the Channel Properties Wizard or click Next to edit additional channel properties.

  4. Complete one of the following steps:
    • If you are editing a channel from an organization, edit the appropriate properties on the Source Organization page. For more information, see Set source organization properties.

    • If you are editing a channel from an application, edit the appropriate properties on the Source Application page. For more information, see Set source application properties.
  5. On the Inbound Document page, edit the appropriate properties.

    For more information, see Set inbound document properties.

  6. On the Outbound Document page, edit the appropriate properties.

    For more information, see Set outbound document properties.

  7. On the Document Logging page, edit the appropriate properties.

    For more information, see Set document logging properties.

  8. On the Advanced Configuration page, edit the appropriate properties.

    For more information, see Set advanced configuration properties.

Notes

  • You cannot name a channel using the reserved system name, Reliable Message Acknowledgement Channel.

  • When you save a channel that references a map that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create channels

Delete channels

Search for channels

Set Channel Properties

Understanding Channels


Delete channels

  1. In BizTalk Messaging Manager, in the Channel Name list, click the channel that you want to delete.

    For information about searching for channels, see Search for channels.

  2. On the File menu, click Delete.

Note

  • You cannot delete the receipt channel until all channels that refer to it have been deleted.

Related Topics

Create channels

Edit channels

Search for channels

Set Channel Properties

Understanding Channels


Set Channel Properties

This section provides task-specific information about how to configure the properties of a channel. The following procedures are covered in this section:

  • Set general channel-information properties

  • Set source organization properties

  • Set source application properties

  • Set inbound document properties

  • Set outbound document properties

  • Set document logging properties

  • Set advanced configuration properties

  • Select a source organization

  • Select a receipt channel

  • Select an inbound document definition

  • Select a certificate to verify inbound document decryption

  • Select a certificate to verify inbound document signature

  • Select an outbound document definition

  • Select a map

  • Select a certificate for outbound signature

  • Override messaging port defaults

  • Override distribution list defaults

  • Set Tracking for Inbound Document Properties

  • Set Channel Filtering Properties


Set general channel-information properties

  1. On the General Information page of the Channel Wizard, in the Name box, type the name of the channel.

  2. In the Comments box, type any comments for the channel.

  3. If you want to create a receipt channel, select the This is a receipt channel check box.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Note

  • You cannot create a receipt channel for an open messaging port or a distribution list.

Related Topics

Create channels

Edit channels

Set Channel Properties

Understanding Receipts


Set source organization properties

  1. On the Source Organization page of the Channel Wizard, complete one of the following steps:
    • Click Open source to create an open channel, which designates that the source is provided either by data within the document or in parameters submitted along with the document, and click Next.

      For more information about submitting documents, see Submitting.

    • Click Organization to designate a trading partner organization as the source and proceed to step 2.
  2. In the Organization area, click Browse.

    The Select an Organization dialog box appears.

  3. Click an organization and click OK.

    For more information, see Select a source organization.

  4. If you want to override the default organization identifier for the source organization, click another identifier in the Organization identifier list.

  5. If you require a receipt from the destination, as specified in the messaging port, select the Expect receipt check box and, in the Receipt interval in minutes box, type a value or click the up or down arrow to increase or decrease the value.

    The default value is 120 minutes. For more information about receipts, see Understanding Receipts.

  6. If you want to generate a receipt to the source, select the Generate receipt check box, click Browse, and then select a receipt channel.

    For more information, see Select a receipt channel.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Notes

  • When you select a source organization identifier for use with X12 envelopes, do not select the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 2 characters or a value that exceeds 15 characters.

  • When you select a source organization identifier for use with EDIFACT envelopes, do not select the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 4 characters or a value that exceeds 35 characters.

  • If you are editing a channel from a specific organization, the Open Source option is not available and you cannot change the source organization. If you are editing an open channel, the Organization option is not available.

  • If you are creating or editing a receipt channel, the Expect receipt and Generate receipt properties are not available.

Related Topics

Create channels

Edit channels

Set Channel Properties

Understanding Receipts


Set source application properties

  1. On the Source Application page of the Channel Wizard, complete one of the following steps:
    • Click XLANG Schedule to designate that the source is an XLANG schedule and click Next.

      You should not choose this option if you are creating a channel for an open messaging port. For more information about integrating BizTalk Messaging Services with BizTalk Orchestration Services, see Integrating BizTalk Services.

    • Click Application to designate an application of the home organization as the source and proceed to step 2.
  2. In the Name list, click an application.

  3. If you want to override the default organization identifier for the home organization, click another identifier in the Organization identifier list.

  4. If you want to receive a receipt from the destination, select the Expect receipt check box and, in the Receipt interval in minutes box, type a value or click the up or down arrow to increase or decrease the value.

    The default value is 120 minutes. For more information about receipts, see Understanding Receipts.

  5. If you want to generate a receipt to the source, select the Generate receipt check box, click Browse, and then select a receipt channel.

    For more information, see Select a receipt channel.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Notes

  • You can create an XLANG schedule by using BizTalk Orchestration Designer.

  • When you are creating or editing a receipt channel, or a channel for which an XLANG schedule is specified as the source, the Expect receipt and Generate receipt properties are not available.

Related Topics

Create channels

Edit channels

Integrating BizTalk Services

Set Channel Properties

Understanding Receipts


Set inbound document properties

  1. On the Inbound Document page of the Channel Wizard, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  2. Click a document definition and click OK.

    For more information, see Select an inbound document definition.

  3. If you want to verify decryption for the inbound document, select the Verify decryption certificate on inbound document check box and, to the right of the Certificate to verify decryption box, click Browse.

    The Select Certificate to Verify Decryption dialog box appears.

  4. Select a certificate.

    For more information, see Select a certificate to verify inbound document decryption.

  5. If you want to verify the digital signature on the inbound document, select the Verify signature certificate on inbound document check box and, to the right of the Certificate to verify signature box, click Browse.

    The Select Certificate to Verify Signature dialog box appears.

  6. Select a signature certificate.

    For more information, see Select a certificate to verify inbound document signature.

  7. If you want to track fields in the inbound document, select the Track inbound document check box and click Tracking.

    The Tracking for Inbound Document dialog box appears.

  8. Set the tracking properties.

    For more information, see Set Tracking for Inbound Document Properties.

  9. If you want to create a channel filtering expression for the inbound document, select the Filter inbound document check box and click Filtering.

    The Channel Filtering Expressions dialog box appears.

  10. Set the filtering properties.

    For more information, see Set Channel Filtering Properties.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Notes

  • When you create a receipt channel that uses the default BizTalk Canonical Receipt for the inbound document definition, the tracking and filtering properties are unavailable.

  • When you create a channel for an open messaging port, and the destination information is provided in the document, the inbound document definition for that channel must reference a specification that is properly configured. For more information about how to configure a document specification to process documents for an open messaging port, see Set dictionary properties.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set dictionary properties

Understanding Receipts


Set outbound document properties

  1. On the Outbound Document page of the Channel Wizard, to the right of the Outbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  2. Click a document definition and click OK.

    For more information, see Select an outbound document definition.

  3. If you want to specify a map, select the Map inbound document to outbound document check box and, to the right of the Map reference box, click Browse.

    The Select a Map from the WebDAV Repository dialog box appears.

  4. Select a map specification.

    For more information, see Select a map.

  5. If you want to digitally sign the outbound document, select the Sign outbound document check box and, to the right of the Signature certificate box, click Browse.

    If you are creating a channel for a messaging port for which the Signature property on the Security Information page is set to S/MIME, the Sign outbound document check box is automatically selected.

    The Select a Signature Certificate dialog box appears.

  6. Select a signature certificate.

    For more information, see Select a certificate for outbound signature.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Important

  • The format of an envelope that you specify in a messaging port must agree with the format of the document or documents that it contains. The document format is determined by the specification referred to in the outbound document definition of an associated channel. For example, if you choose an envelope with an X12 format for a messaging port, you must select an outbound document definition for the channel that points to an X12 specification.

  • When you declare a messaging port as an open messaging port, you should not create channels for the messaging port that have an outbound document definition with an X12 or EDIFACT specification. To build an X12 or EDIFACT envelope, the server must have a source and a destination organization identifier. An open messaging port does not specify a destination organization identifier. In addition, the documents for an open messaging port must have the destination address within the document, but X12 and EDIFACT documents do not contain this information.

  • The first time that you open any WebDAV repository dialog box, the WebDAV repository on the local server is selected, even if your BizTalk Messaging Manager is connected to a database on a remote server. If you browse to a WebDAV repository on a remote server, the default changes to that server until you select a new WebDAV repository. The default server for all WebDAV repository dialog boxes is the last server to which a connection was made.

Note

  • A map is used to transform the inbound document format into the outbound document format. If the specification reference of the inbound document matches that of the outbound document, no map is required. By default, the Map inbound document to outbound document check box is not selected. Maps can be created using BizTalk Mapper. For more information about maps, see Using BizTalk Mapper.

Related Topics

Create channels

Edit channels

Set Channel Properties

Understanding Receipts


Set document logging properties

  1. On the Document Logging page of the Channel Wizard, in the Log inbound document area, select the appropriate check boxes:
    • In native format. Stores inbound documents for the channel in the original format. This is the default setting.

    • In XML format. Stores inbound documents for the channel in XML format.
  2. In the Log outbound document area, select the appropriate check boxes:
    • In native format. Stores outbound documents for the channel in the original format.

    • In XML format. Stores outbound documents for the channel in XML format.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

If you have completed your changes, click Finish.

Notes

  • There is a size limit for documents that use logging, which if exceeded will greatly affect the performance of BizTalk Server. For more information about the size limit, see Interchange and document size limit.

  • BizTalk Server translates non-XML inbound documents from their original, native format into an XML format for processing, and outbound documents from an XML format into the required, native format of the destination.

Related Topics

Create channels

Edit channels

Set Channel Properties


Set advanced configuration properties

  1. On the Advanced Configuration page of the Channel Wizard, if you are creating a channel for a messaging port that specifies an X12 or EDIFACT envelope format, in the Group control number box, type a non-zero value.

  2. In the Retry options area, in the Number of retries box, enter the number of times that you want the server to resend the document if a receipt has not been received and, in the Interval box, enter the number of minutes between retries.

    For more information about receipts, see Understanding Receipts.

  3. If you want to override the transport or envelope component settings for a messaging port or distribution list, click Advanced.
    • If you are creating or editing a channel for a messaging port, the Override Messaging Port Defaults dialog box appears. For more information, see Override messaging port defaults.

    • If you are creating or editing a channel for a distribution list, the Override Distribution List Defaults dialog box appears. For more information, see Override distribution list defaults.

If you are creating a new channel, click Next. For instructions about completing the next step, go to Create channels.

If you are editing an existing channel, click Next. For instructions about completing the next step, go to Edit channels.

  • If you have completed your changes, click Finish.

Related Topics

Create channels

Edit channels

Retry queue

Set Channel Properties

Understanding Receipts


Select a source organization

  1. On the Source Organization page of the Channel Wizard, to the right of the Name box, click Browse.

    The Select an Organization dialog box appears.

  2. In the Available organizations list, click an organization and click OK.

To continue setting source organization properties, go to Set source organization properties.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set source organization properties


Select a receipt channel

  1. On the Source Application or Source Organization page of the Channel Wizard, select the Generate receipt check box and click Browse.

    The Select a Receipt Channel dialog box appears.

  2. In the Available receipt channels list, click a receipt channel and click OK.

To continue setting source organization properties, go to Set source organization properties.

To continue setting source application properties, go to Set source application properties.

Note

  • The Available receipt channels list displays only receipt channels that are associated with messaging ports for which the destination is identical to the source for the channel that you are creating. When BizTalk Server invokes a channel with a receipt channel specified, the server returns a receipt to the original source of that document by using the receipt channel specified. For more information about receipts, see Understanding Receipts.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set source application properties

Set source organization properties

Understanding Receipts


Select an inbound document definition

  1. On the Inbound Document page of the Channel Wizard, to the right of the Inbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  2. In the Available document definitions list, click a document definition and click OK.

To continue setting inbound document properties, go to Set inbound document properties.

Note

  • When you create a receipt channel, both the inbound and outbound document definitions default to the BizTalk Canonical Receipt and cannot be transformed by using a map. To use a different format for an outbound receipt, you must create and select an inbound document definition that refers to the canonical receipt specification in the WebDAV repository. You also must create an outbound document definition that refers to a specification with the format that you want for the outbound receipt, as well as a map that transforms the format of the receipt. For more information about receipts, see Understanding Receipts.

Related Topics

Create channels

Create document definitions

Edit channels

Set Channel Properties

Set inbound document properties

Understanding Receipts


Select a certificate to verify inbound document decryption

  1. On the Inbound Document page of the Channel Wizard, select the Verify decryption on inbound document check box and, to the right of the Certificate to verify decryption box, click Browse.

    The Select a Certificate to Verify Decryption dialog box appears.

  2. In the Certificate name list, click a certificate name and click OK.

To continue setting inbound document properties, go to Set inbound document properties.

Notes

  • All certificates are stored in the local computer store. To configure certificates for the S/MIME components by using BizTalk Messaging Manager, you must belong to a user account in the Windows 2000 Administrators group, and BizTalk Messaging Services must be running as a local system account or as a user account in the Windows 2000 Administrators group.

  • Documents are decrypted when BizTalk Server receives them so that the server can obtain the data it needs to identify the appropriate channel. The certificate that you specify in the channel verifies that the decryption was done correctly.

  • All certificates must be named uniquely. If more than one certificate has the same name, only one of the certificates can be selected. Once one of the certificates is selected, other certificates with the same name no longer appear in the list.

    For more information about certificates, see Certificates Overview.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set inbound document properties


Select a certificate to verify inbound document signature

  1. On the Inbound Document page of the Channel Wizard, select the Verify signature on inbound document check box and, to the right of the Certificate for signature verification box, click Browse.

    The Select a Certificate to Verify Signature dialog box appears.

  2. In the Certificate name list, click a certificate name and click OK.

To continue setting inbound document properties, go to Set inbound document properties.

Notes

  • All certificates are stored in the local computer store. To configure certificates for the S/MIME components by using BizTalk Messaging Manager, you must belong to a user account in the Windows 2000 Administrators group, and BizTalk Messaging Services must be running as a local system account or as a user account in the Windows 2000 Administrators group.

  • All certificates must be named uniquely. If more than one certificate has the same name, only one of the certificates can be selected. Once one of the certificates is selected, other certificates with the same name no longer appear in the list.

    For more information about certificates, see Certificates Overview.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set inbound document properties


Select an outbound document definition

  1. On the Outbound Document page of the Channel Wizard, to the right of the Outbound document definition name box, click Browse.

    The Select a Document Definition dialog box appears.

  2. In the Available document definitions list, click a document definition and click OK.

To continue setting outbound document properties, go to Set outbound document properties.

Note

  • When you create a receipt channel, both the inbound and outbound document definitions default to the BizTalk Canonical Receipt and cannot be transformed by using a map. To use a different format for an outbound receipt, you must create and select an inbound document definition that refers to the canonical receipt specification in the WebDAV repository. You also must create an outbound document definition that refers to a specification with the format that you want for the outbound receipt, as well as a map that transforms the format of the receipt. For more information about receipts, see Understanding Receipts.

Related Topics

Create channels

Create document definitions

Edit channels

Set Channel Properties

Set outbound document properties

Understanding Receipts


Select a map

  1. On the Outbound Document page of the Channel Wizard, select the Map inbound document to outbound document check box and, to the right of the Map reference box, click Browse.

    The Select a Map from the WebDAV Repository dialog box appears.

  2. In the Server box, do one of the following if you want to change the server:
    • Click a server in the list.

    • Type the name of a server and press ENTER.
  3. Double-click the folder that contains the map that you want, click the map, and then click Open.

To continue setting outbound document properties, go to Set outbound document properties.

Important

  • The first time that you open any WebDAV repository dialog box, the WebDAV repository on the local server is selected, even if your BizTalk Messaging Manager is connected to a database on a remote server. If you browse to a WebDAV repository on a remote server, the default changes to that server until you select a new WebDAV repository. The default server for all WebDAV repository dialog boxes is the last server to which a connection was made.

Notes

  • If you select http://localhost as the server, BizTalk Messaging Manager automatically converts it to the local computer name.

  • When you save a channel that references a map that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create channels

Edit channels

Using BizTalk Mapper

Set Channel Properties

Set outbound document properties


Select a certificate for outbound signature

  1. On the Outbound Document page of the Channel Wizard, select the Sign outbound document check box and, to the right of the Signature certificate box, click Browse.

    The Select a Signature Certificate dialog box appears.

  2. In the Certificate name list, click a certificate name and click OK.

To continue setting outbound document properties, go to Set outbound document properties.

Notes

  • All certificates are stored in the local computer store. To configure certificates for the S/MIME components by using BizTalk Messaging Manager, you must belong to a user account in the Windows 2000 Administrators group, and BizTalk Messaging Services must be running as a local system account or as a user account in the Windows 2000 Administrators group.

  • All certificates must be named uniquely. If more than one certificate has the same name, only one of the certificates can be selected. Once one of the certificates is selected, other certificates with the same name no longer appear in the list.

    For more information about certificates, see Certificates Overview.

Related Topics

Create channels

Edit channels

Set Channel Properties

Set outbound document properties


Override messaging port defaults

  1. On the Advanced Configuration page of the Channel Wizard, click Advanced.

    If you are creating or editing a channel for a messaging port, the Override Messaging Port Defaults dialog box appears.

  2. On the Primary Transport tab, click Properties.

    The BizTalk Component Properties dialog box appears.

  3. Change the transport component properties that you want to override and click OK.

  4. If the messaging port has an envelope and you want to override its settings, click the Envelope tab and click Properties.

    The BizTalk Component Properties dialog box appears.

  5. Change the envelope component properties that you want to override and click OK.

To continue setting advanced properties, go to Set advanced configuration properties.

Important

  • Overriding the transport and envelope properties for a messaging port is an advanced feature. If you do not thoroughly understand the transport or envelope component properties in these dialog boxes, you should not change them.

  • If you specified an envelope with a custom format in the messaging port, you must configure the custom serializer component by using the advanced configuration properties.

Notes

  • When you override messaging port properties in a channel, the overrides apply only to that channel.

  • You cannot override the transport address that was set in a messaging port.

  • The default setting for the HTTP transport component is to use the HTTP proxy server. This is the correct setting to transport data to Web sites outside your business's firewall. To transport data to Web sites that are inside your business's firewall (that is, within your intranet), use this procedure to override the default setting.

  • For the HTTPS transport component, use only certificates that are specified for client authentication. Certificates that are specified for all purposes do not appear in the list.

  • The default setting for the file transport component is to append files. If you choose the file transport type with its default settings in a messaging port and use antivirus software on the server on which BizTalk Server is installed, and you send multiple files that have exactly the same name to the same file location, at the same time, BizTalk Server might stop responding and must be restarted. You can eliminate this problem by changing the default setting for the file transport component from Append to file to Overwrite file in the BizTalk SendLocalFile Properties dialog box. You also can eliminate this problem by creating a unique file for each document instance processed by using the file path format in the messaging port: file://C:\dir\file%tracking_id%.xml. For more information, see Specify a transport address.

  • The default setting for the file transport component is to append files. If you choose the file transport type with its default settings and select an envelope with a reliable envelope format in a messaging port, and then send multiple files to the same file location, at the same time, you might have unexpected parsing results. You can eliminate this problem by changing the default setting for the file transport component from Append to file to Overwrite file in the BizTalk SendLocalFile Properties dialog box.

  • If the envelope specified in the messaging port has a custom format, and you have created and registered a custom serializer component, you can configure the properties of the custom serializer component by using this procedure.

  • The default syntax identifier for an EDIFACT envelope is UNOA (uppercase Latin alphabet). If your data requires a different syntax, select a different syntax identifier by using this procedure.

  • If you use EDIFACT release indicators, do not include release indicator characters in your data. Doing so might cause the data to exceed the physical character size limits for fields.

Related Topics

Create channels

Edit channels

Set advanced configuration properties

Set Channel Properties


Override distribution list defaults

  1. On the Advanced Configuration page of the Channel Wizard, click Advanced.

    If you are creating or editing a channel for a distribution list, the Override Distribution List Defaults dialog box appears.

  2. In the Select Messaging Port list, select a messaging port that you want to override and click Override.

    The Override Messaging Port Defaults dialog box appears.

  3. Override the transport and envelope component properties for the selected messaging port.

    For more information, see Override messaging port defaults.

  4. When you have changed the messaging ports that you want to override, click Close.

To continue setting advanced properties, go to Set advanced configuration properties.

Related Topics

Create channels

Edit channels

Override messaging port defaults

Set advanced configuration properties

Set Channel Properties


Set Tracking for Inbound Document Properties

The Tracking for Inbound Document dialog box lists the specification fields for the inbound document, as well as any global tracking fields selected in the document definition.

If you select any specification fields by using this dialog box, those fields override the global tracking fields for this channel only. For each document instance that is processed, the fields that you select in the channel are logged to the Tracking database, rather than to the global tracking fields.

This section describes how to select or remove specification fields of the inbound document in a channel.

The following procedures are covered in this section:

  • Select specification fields in a channel

  • Remove specification fields in a channel

Related Topics

Create channels

Edit channels

Set Channel Properties

Set Global Tracking Properties

Set inbound document properties


Select specification fields in a channel

  1. On the Inbound Document page of the Channel Wizard, select the Track inbound document check box and click Tracking.

    The Tracking for Inbound Document dialog box appears.

  2. In the Specification fields tree, double-click any record to expand the view.

  3. Select a specification field that you want to add to the Fields to track list and complete one of the following procedures:
    To add the field as | Follow this procedure
    Integer | Click Integer. You can add two fields as integers.
    Real | Click Real. You can add two fields as real numbers.
    Date | Click Date. You can add two fields as dates.
    Text | Click Text. You can add two fields as text.
    Custom | Click Custom. You can add unlimited fields as a custom type. The fields are stored as an XML concatenated string with tags for each field.

To continue setting inbound document properties, go to Set inbound document properties.

Important

  • If you select any specification fields by using this dialog box, those fields override the global tracking fields for this channel only. For each document instance that is processed, the fields that you select in the channel are logged to the Tracking database, rather than to the global tracking fields.

Notes

  • To select a specification field to track as an integer, real, or date data type, the field must have that data type assigned in the specification. For more information about assigning a data type to a specification field, see Set declaration properties.

  • Specification fields without a data type assigned in the specification can be tracked only as a text or custom data type.

  • If a specification field that you want to track has a character data type, you can track that field only as a custom data type.

  • You can select only two specification fields of a specific data type. You can select an unlimited number of fields as a custom data type.

Related Topics

Create channels

Edit channels

Remove specification fields in a channel

Set Channel Properties

Set Global Tracking Properties

Set Tracking for Inbound Document Properties

Tracking Document Data Fields


Remove specification fields in a channel

  1. On the Inbound Document page of the Channel Wizard, select the Track inbound document check box and click Tracking.

    The Tracking for Inbound Document dialog box appears.

  2. In the Fields to track list, click the specification field or fields that you want to remove and click Remove.

To continue setting inbound document properties, go to Set inbound document properties.

Note

  • When you remove a field from the list of fields to track, it is removed only from the list in this channel; it is not removed from the specification.

Related Topics

Create channels

Edit channels

Select specification fields in a channel

Set Channel Properties

Set Global Tracking Properties

Set Tracking for Inbound Document Properties

Tracking Document Data Fields


Set Channel Filtering Properties

A channel filtering expression is an XPath expression that can be used to determine if a channel is invoked based upon the value of a specified field or fields within the document. When BizTalk Server processes a document, the value of the specified field or fields in each document is evaluated against the channel filtering expression. If the expression is found to be true, the channel is invoked. If the expression is found to be false, the channel is not invoked.

The following procedures are covered in this section:

  • Add a channel filtering expression

  • Edit a channel filtering expression

  • Remove a channel filtering expression

Related Topic

Set inbound document properties


Add a channel filtering expression

  1. On the Inbound Document page of the Channel Wizard, select the Filter inbound document check box and click Filtering.

    The Channel Filtering Expressions dialog box appears.

  2. In the Select field tree, double-click any node to expand the view.

  3. Click a specification field that you want to use to create a filtering expression and click Add.

    The Expression Properties dialog box appears.

  4. In the Operator list, click an operator:
    Operator Symbol
    Equal to (Default) =
    Not equal to !=
    Less than <
    Equal to or less than <=
    Greater than >
    Equal to or greater than >=

  5. In the Value box, type a value for the expression and click OK.

To continue setting inbound document properties, go to Set inbound document properties.

Important

  • A channel filtering expression must be a valid XPath expression. The Add button can be used to create a clause that contains a specification field and to insert it into an expression; however, it does not generate the correct syntax needed for a valid XPath expression. For more information about XPath expressions, see Channel Filtering; you can also go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on the keyword "XPath."

Notes

  • You can type an expression directly into the Expressions list.

  • To select a specification field for a channel filtering expression, the field must have a data type assigned in the specification. For more information about assigning a data type to a field, see Set declaration properties.

  • If the specification field that you are using to create an expression has a Boolean data type, you cannot use the text string "true" or "false" in the expression value. You must use a numerical value instead, "-1" for true and "0" for false.

  • If the specification field that you are using to create an expression has a date data type, you must type the value in the following format, including the hyphens: YYYY-MM-DD.

  • If you want to use a filter for a date/time type (dateTime, dateTime.tz, time, time.tz), you must type it manually in the XPath expression. For example, self::node()[@ATTDATETIME = "2000-03-15T10:10:10"] where ATTDATETIME is the date/time format type.

Related Topics

Create channels

Edit a channel filtering expression

Edit channels

Remove a channel filtering expression

Set Channel Filtering Properties

Set Channel Properties


Edit a channel filtering expression

  1. On the Inbound Document page of the Channel Wizard, select the Filter inbound document check box and click Filtering.

    The Channel Filtering Expressions dialog box appears.

  2. In the Expressions list, edit the expression and click OK.

To continue setting inbound document properties, go to Set inbound document properties.

Important

  • A channel filtering expression must be a valid XPath expression. For more information about XPath expressions, see Channel Filtering; you can also go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search on the keyword "XPath."

Related Topics

Add a channel filtering expression

Remove a channel filtering expression

Set Channel Filtering Properties


Remove a channel filtering expression

  • On the Inbound Document page of the Channel Wizard, clear the Filter inbound document check box.

To continue setting inbound document properties, go to Set inbound document properties.

Related Topics

Add a channel filtering expression

Create channels

Edit a channel filtering expression

Edit channels

Set Channel Filtering Properties

Set Channel Properties


Create and Manage Messaging Ports

This section provides task-specific information about how to create and manage messaging ports. It is highly recommended that you review Understanding Messaging Ports to fully understand messaging ports.

The following procedures are covered in this section:

  • Create messaging ports

  • Search for messaging ports

  • Edit messaging ports

  • Delete messaging ports

  • Set Messaging Port Properties


Create messaging ports

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. On the File menu, point to New, point to Messaging Port, and then complete one of the following steps:
    • To create a messaging port to a trading partner organization, click To an Organization.

    • To create a messaging port to an internal application, click To an Application.

    The New Messaging Port Properties Wizard opens.

  3. On the General Information page, set the properties and click Next.

    For more information, see Set general messaging-port information properties.

  4. Complete one of the following steps:
    • If you are creating a messaging port to a specific organization, set the properties on the Destination Organization page and click Next. For more information, see Set destination organization properties.

    • If you are creating an open messaging port, click Open destination and click Next.

      For an open messaging port, the transport and destination information must be provided either within the document or in a parameter submitted with the document. For more information, see Submitting.

    • If you are creating a messaging port to an application, set the properties on the Destination Application page and click Next. For more information, see Set destination application properties.
  5. On the Envelope Information page, set the properties and click Next.

    For more information, see Set envelope information properties.

  6. On the Security Information page, set the properties.

    For more information, see Set security information properties.

  7. If you do not want to proceed directly to the Channel Wizard to create a channel, clear the Create a channel for this messaging port check box; otherwise, in the Channel type list, click one of the following channel types:
    • From an organization

    • From an application
  8. After you have set all messaging port properties, on the Security Information page, click Finish to close the New Messaging Port Properties Wizard.

Important

  • When you declare a messaging port as an open messaging port, do not create channels for the messaging port that have an outbound document definition with an X12 or EDIFACT specification. To build an X12 or EDIFACT envelope, the server must have a source and a destination organization identifier. An open messaging port does not specify a destination organization identifier. In addition, the documents for an open messaging port must have the destination address within the document, but X12 and EDIFACT documents do not contain this information.

Notes

  • You cannot name a messaging port using the reserved system name, Reliable Message Acknowledgement Port.

  • If you create a messaging port and a channel to use for a pass-through submission of data, you can use only the service window and the retry count and interval features of the channel, and the transport features of its associated messaging port. You cannot use the verification of decoding or decryption, filtering, document tracking, or mapping features of the channel.

Related Topics

Create and Manage Channels

Delete messaging ports

Edit messaging ports

Search for messaging ports

Set Messaging Port Properties

Understanding Messaging Ports


Search for messaging ports

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the Search for other items area, click Messaging ports.

  3. Do one or more of the following:
    • To search for all messaging ports, clear all search criteria and click Search Now.

    • To search for a messaging port with a specific name, in the Messaging port name box, type the name of the messaging port that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for messaging ports to a specific type of destination, in the Destination list, click a destination type and click Search Now.

Notes

  • You can set more than one search criteria before clicking Search Now.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • To clear the search criteria and search results, click Clear Search.

  • You can use the following wildcard characters in the search criteria.
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Delete messaging ports

Edit messaging ports

Understanding Messaging Ports


Edit messaging ports

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the Messaging Port Name list, click the messaging port that you want to edit.

    For information about searching for messaging ports, see Search for messaging ports.

  3. On the File menu, click Edit.

    The Messaging Port Properties Wizard opens.

  4. On the General Information page, edit the appropriate properties.

    For more information, see Set general messaging-port information properties.

    After editing the properties on any page, you can click Finish to close the Messaging Port Properties Wizard or click Next to edit additional messaging port properties.

  5. Complete one of the following steps:
    • If you are editing a messaging port to an organization, edit the necessary properties on the Destination Organization page and click Next. For more information, see Set destination organization properties.

    • If you are editing a messaging port to an application, edit the appropriate properties on the Destination Application page and click Next. For more information, see Set destination application properties.
  6. On the Envelope Information page, edit the appropriate properties and click Next.

    For more information, see Set envelope information properties.

  7. On the Security Information page, edit the appropriate properties.

    For more information, see Set security information properties.

  8. If you do not want to proceed directly to the Channel Wizard to create a channel, clear the Create a channel for this messaging port check box; otherwise, in the Channel type list, click one of the following channel types:
    • From an organization

    • From an application
  9. After you have edited all appropriate messaging port properties, you can click Finish on any page to close the Messaging Port Properties Wizard.

Note

  • You cannot name a messaging port using the reserved system name, Reliable Message Acknowledgement Port.

Related Topics

Create and Manage Channels

Create messaging ports

Delete messaging ports

Set Messaging Port Properties

Understanding Messaging Ports


Delete messaging ports

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the Messaging Port Name list, click the messaging port that you want to delete.

    For information about searching for messaging ports, see Search for messaging ports.

  3. On the File menu, click Delete.

Notes

  • If you have created channels for a messaging port, you cannot delete the messaging port until its associated channels have been deleted.

  • You can search for channels associated with a messaging port by right-clicking the messaging port and clicking Find Channels.

Related Topics

Create and Manage Channels

Create messaging ports

Edit messaging ports

Understanding Messaging Ports


Set Messaging Port Properties

This section provides task-specific information about how to configure the properties of a messaging port.

The following procedures are covered in this section:

  • Set general messaging-port information properties

  • Set destination organization properties

  • Set destination application properties

  • Set envelope information properties

  • Set security information properties

  • Select a destination organization

  • Select an encryption certificate

  • Set Transport Properties

  • Set Envelope Delimiters


Set general messaging-port information properties

  1. On the General Information page of the Messaging Port Properties Wizard, in the Name box, type the name of the messaging port.

  2. In the Comments box, type any comments that you want for the messaging port and click Next.

If you are creating a new messaging port, click Next. For instructions about completing the next step, go to Create messaging ports.

If you are editing an existing messaging port, click Next. For instructions about completing the next step, go to Edit messaging ports.

If you have completed your changes, click Finish.

Related Topics

Create messaging ports

Edit messaging ports

Set Messaging Port Properties


Set destination organization properties

  1. On the Destination Organization page of the Messaging Port Properties Wizard, complete one of the following steps:
    • Click Open destination to create an open messaging port and click Next.

      For an open messaging port, the transport and destination information must be provided either within the document or in parameters submitted with the document. For more information, see Submitting.

    • Click Organization to designate a specific trading partner organization as the destination and then proceed to step 2.
  2. In the Organization area, click Browse.

    The Select an Organization dialog box appears.

  3. Click an organization and click OK.

    For more information, see Select a destination organization.

  4. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  5. Set the primary transport properties.

    For more information, see Set Transport Properties.

  6. If you want to limit the time when documents can be transported, in the Primary transport area, select the Service window check box.

    Then, in the From and To boxes, click the hour and enter a value, or click the up or down arrow to increase or decrease the value.

  7. If you want to specify a secondary transport, in the Backup transport area, click Browse.

    The Backup Transport dialog box appears.

  8. Set the backup transport properties.

    For more information, see Set Transport Properties.

If you are creating a new messaging port, click Next. For instructions about completing the next step, go to Create messaging ports.

If you are editing an existing messaging port, click Next. For instructions about completing the next step, go to Edit messaging ports.

If you have completed your changes, click Finish.

Important

  • When you declare a messaging port as an open messaging port, do not create channels for the messaging port that have an outbound document definition with an X12 or EDIFACT specification. To build an X12 or EDIFACT envelope, the server must have a source and a destination organization identifier. An open messaging port does not specify a destination organization identifier. In addition, the documents for an open messaging port must have the destination address within the document, but X12 and EDIFACT documents do not contain this information.

Note

  • Service window hours are displayed in coordinated universal time (UTC) format and reflect the time on the server.

Related Topics

Create messaging ports

Edit messaging ports

Set Messaging Port Properties


Set destination application properties

  1. On the Destination Application page of the Messaging Port Properties Wizard, complete one of the following steps:
    • Click New XLANG schedule to designate a port in a new instance of a specified XLANG schedule as the destination. In the Schedule moniker box, type the moniker of the specified schedule or click Browse to set the path. Then, in the Port name box, type the name of the specific port in this schedule to which the document is sent.

      The syntax for schedule monikers is as follows:

      sked://[localhost][!GroupManager][/FilePath][/PortName]

      You can activate XLANG schedules only on the local computer.

      For more information about monikers, see Moniker Syntax.

    • Click Running XLANG schedule to designate an active XLANG schedule instance as the destination. Use this option only to transport a message to an active XLANG schedule when a trading partner returns the message to a specially configured ASP page using an HTTP transport. For more information, see Integrating BizTalk Services.

    • Click Application to designate an application of the home organization as the destination, and then click an application in the Name list.
  2. If you selected an application as the destination, complete steps 3 through 5; otherwise, click Next.

  3. In the Primary transport area, click Browse.

    The Primary Transport dialog box appears.

  4. Set the primary transport properties.

    For more information, see Set Transport Properties.

  5. If you want to limit the time when documents can be transported, in the Primary transport area, select the Service window check box.

    Then, in the From and To boxes, click the hour and enter a value, or click the up or down arrow to increase or decrease the value.

  6. If you want to specify a secondary transport, in the Backup transport area, click Browse.

    The Backup Transport dialog box appears.

  7. Set the backup transport properties.

    For more information, see Set Transport Properties.

If you are creating a new messaging port, click Next. For instructions about completing the next step, go to Create messaging ports.

If you are editing an existing messaging port, click Next. For instructions about completing the next step, go to Edit messaging ports.

If you have completed your changes, click Finish.

Important

  • If you choose the New XLANG schedule option:
    • The port that you name must be bound to BizTalk Messaging in the specified schedule, and that binding must be configured to activate a new schedule instance upon message arrival.

    • You should have only one port in a schedule that is configured to activate a new schedule instance upon message arrival, and it should be the first action in the schedule. For more information, see Implement a port by using BizTalk Messaging.

Notes

  • If you choose an XLANG schedule as the destination for a messaging port, there is a maximum limit of 2 MB for the documents that you process by using this messaging port.

  • BizTalk Orchestration Designer can be used to create XLANG schedules.

  • Service window times are displayed in coordinated universal time (UTC) format and reflect the time on the server.

Related Topics

Create messaging ports

Edit messaging ports

Set Messaging Port Properties


Set envelope information properties

  1. On the Envelope Information page of the Messaging Port Properties Wizard, in the Envelope information area, select an envelope from the list.

    If you select an envelope that has an X12 or EDIFACT format, the following steps are required. If you select an envelope that has a custom format, the following steps are optional.

    1. Click Delimiters and set the delimiter properties.

      For more information, see Set Envelope Delimiters.

    2. In the Interchange control number box, type an interchange control number.
  2. If you want to override the default organization identifier for the destination organization, click another identifier in the Organization identifier list.

If you are creating a new messaging port, click Next. For instructions about completing the next step, go to Create messaging ports.

If you are editing an existing messaging port, click Next. For instructions about completing the next step, go to Edit messaging ports.

If you have completed your changes, click Finish.

Important

  • If you choose an envelope with a reliable format, you also must configure the Reliable messaging reply-to URL address in the BizTalk Server Group Properties dialog box. For more information, see Configure general properties for a server group.

  • The format of an envelope that you specify in a messaging port must agree with the format of the document or documents that it contains. The document format is determined by the specification referred to in the outbound document definition of an associated channel. For example, if you choose an envelope with an X12 format for a messaging port, you must select an outbound document definition for the channel that points to an X12 specification.

Notes

  • When processing envelopes that are compliant with BizTalk Framework 2.0, BizTalk Server 2002 should be considered the endpoint with regard to the expiration time. When BizTalk Framework 2.0–compliant documents are submitted to BizTalk Server 2002, either from an application or a trading partner, the following fields are overwritten if present, or created if absent:
    • In the properties subsection:

      <prop:identity>

      <prop:sentAt>

      <prop:expiresAt>

    • In the receipt information subsection:

      <sendTo>

      <address>

      <sendReceiptBy>

  • For a messaging port to an application, the organization identifiers available in the Organization identifier list are those of the home organization.

  • If you use the Loopback transport type, you cannot choose an envelope with a reliable format.

  • When you select a destination organization identifier for use with X12 envelopes, you should not select the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 2 characters or a value that exceeds 15 characters.

  • When you select a destination organization identifier for use with EDIFACT envelopes, you should not select the organization identifier named Organization, or any other identifier that has a qualifier that exceeds 4 characters or a value that exceeds 35 characters.

  • If you select an envelope with an EDIFACT format, the default syntax identifier is UNOA (uppercase Latin alphabet). If your data requires a different syntax, select a different syntax identifier by overriding the messaging port defaults in the Channel Wizard. For more information, see Override messaging port defaults.

Related Topics

Create envelopes

Create messaging ports

Edit messaging ports

Set Messaging Port Properties

Understanding Envelopes


Set security information properties

  1. On the Security Information page of the Messaging Port Properties Wizard, in the Encoding area, in the Type list, click one the following:
    • (None). Specifies no encoding. This is the default setting.

    • MIME. Specifies encoding that uses Multipurpose Internet Mail Extensions.

    • Custom. Specifies encoding that uses a custom encoding component.

    Notes

    • You can specify a custom encoding/encryption/signature component and configure the class identifier (CLSID) only by using the BizTalk Messaging Configuration object model. BizTalk Messaging Manager displays "Custom" in the encoding/encryption/signature Type list only when you are editing a messaging port for which a custom component has been specified.

    • If you specify an envelope that uses a reliable format, or an envelope that uses a custom XML format without an envelope specification, and your document has no attachments, your output is not MIME encoded, even if you specify MIME encoding.

    • If the incoming document is MIME-encoded Shift-JIS data, do not specify "encoding=Shift_jis" in the body of the document. Instead, specify "charset=shift-jis" in the MIME header.
  2. In the Encryption area, in the Type list, click one of the following:
    • (None). Specifies no encryption. This is the default setting.

    • S/MIME. Specifies encryption that uses Secure Multipurpose Internet Mail Extensions.

    • Custom. Specifies encoding that uses a custom encryption component.

    Note

    • You can specify a custom encryption component and configure the class identifier (CLSID) only by using the BizTalk Messaging Configuration object model.
  3. If you select S/MIME encryption, in the Encryption area, click Browse.

    The Select an Encryption Certificate dialog box appears.

  4. Select an encryption certificate.

    For more information, see Select an encryption certificate.

  5. In the Signature area, in the Type list, click one of the following:
    • (None). Specifies no signature. This is the default setting.

    • S/MIME. Specifies a signature that uses Secure Multipurpose Internet Mail Extensions.

    • Custom. Specifies encoding that uses a custom signature component.

    Note

    • You can specify a custom signature component and configure the class identifier (CLSID) only by using the BizTalk Messaging Configuration object model.
  6. If you do not want to proceed directly to the Channel Wizard to create a channel, clear the Create a channel for this messaging port check box; otherwise, in the Channel type list, click one of the following channel types:
    • From an organization

    • From an application

If you are creating a new messaging port, click Next. For instructions about completing the next step, go to Create messaging ports.

If you are editing an existing messaging port, click Next. For instructions about completing the next step, go to Edit messaging ports.

If you have completed your changes, click Finish.

Related Topics

Create channels

Create messaging ports

Edit messaging ports

Set Messaging Port Properties


Select a destination organization

  1. On the Destination Organization page of the Messaging Port Properties Wizard, click Organization and click Browse.

    The Select an Organization dialog box appears.

  2. In the Available organizations list, click an organization and click OK.

To continue setting destination organization properties, go to Set destination organization properties.

Related Topics

Create messaging ports

Set destination organization properties

Set Messaging Port Properties


Select an encryption certificate

  1. On the Security Information page of the Messaging Port Properties Wizard, in the Encryption area, in the Type list, click S/MIME and click Browse.

    The Select an Encryption Certificate dialog box appears.

  2. In the Certificate name list, click a certificate name and click OK.

To continue setting security properties, go to Set security information properties.

Note

  • All certificates must be named uniquely. If more than one certificate has the same name, only one of the certificates can be selected. Once one of the certificates is selected, other certificates with the same name no longer appear in the list.

    For more information about certificates, see Certificates Overview.

Related Topics

Create messaging ports

Set Messaging Port Properties

Set security information


Set Transport Properties

Transport properties include a transport type. The transport type specifies which transport service Microsoft BizTalk Server 2002 uses to convey documents to the destination designated in the messaging port. Transport properties can also include a specific address to which the data is sent. The address properties vary based on the transport type selected.

This section describes how to set the primary and backup transport properties for a messaging port.

The following procedures are covered in this section:

  • Select a transport type

  • Specify a transport address

  • Select an application integration component

  • Change the default SMTP Subject value


Select a transport type

  1. On the Destination Application or Destination Organization page of the Messaging Port Properties Wizard, in the Primary transport or Backup transport area, click Browse.

    The Primary Transport or Backup Transport dialog box appears.

  2. In the Transport type list, click one of the following transport types:
    • Application Integration Component. Specifies a transport that uses an application integration component (AIC) that has been registered with BizTalk Server 2002.

    • File. Specifies a transport that uses the SendLocalFile component.

    • HTTP. Specifies a transport that uses the Hypertext Transfer Protocol.

    • HTTPS. Specifies a transport that uses the Secure Hypertext Transfer Protocol.

    • Loopback. Specifies a transport that returns the outbound document of a channel to a business application, component, or XLANG schedule that submitted the inbound document using a synchronous submit call. This transport type is available only for a messaging port that sends documents to an application.

    • Message Queuing. Specifies a transport that uses the Message Queuing service.

    • SMTP. Specifies a transport that uses the Simple Mail Transfer Protocol.
  3. Complete one of the following steps:
    • If you choose the Application Integration Component transport type, see Select an application integration component.

    • If you choose the Loopback transport type, no transport address is required.

    • If you choose any other transport type, see Specify a transport address.

Notes

  • If you choose the Message Queuing transport type and do not use an envelope, there is a maximum size limit of 2 MB for the documents that you process by using this messaging port.

  • If you choose the Message Queuing transport type and use an envelope, there is a maximum size limit of 4 MB for the documents that you process by using this messaging port.

  • Before you can choose the SMTP transport type, you must configure the SMTP host in BizTalk Server Administration. For more information, see Configure general properties for a server group.

  • The default setting for the HTTP transport component is to use the HTTP proxy server. This is the correct setting to transport data to Web sites outside your business's firewall. To transport data to Web sites that are inside your business's firewall (that is, within your intranet), override the default setting in the channel. For more information, see Override messaging port defaults.

  • The Loopback transport type can be used to map an inbound document to a different format, envelope or apply security (encoding, encryption, digital signature) to the document, and then synchronously return the outbound document to the caller as the response document.

  • If you choose the Loopback transport type, you cannot use an envelope with a reliable format.

Related Topics

Create messaging ports

Select an application integration component

Set Messaging Port Properties

Set Transport Properties

Specify a transport address

Change the default SMTP Subject value


Specify a transport address

  1. On the Destination Application or Destination Organization page of the Messaging Port Properties Wizard, in the Primary transport or Backup transport area, click Browse.

    The Primary Transport or Backup Transport dialog box appears.

  2. In the Transport type list, click a transport type other than Loopback or Application Integration Component.

  3. In the Address box, type an address for the destination.

  4. If you selected the SMTP transport type, in the Return e-mail address box, type an address.

    The server uses this address as the From address in the outbound header and as the destination for return e-mail.

To continue setting destination organization properties, go to Set destination organization properties.

Important

  • For the File transport type, the default transport-component setting is to append new files to an existing file in the specified directory.

  • If you use the File transport to send multiple files with the same name to the same directory, and the files have different document formats or use different code pages, the data in the appended file will be corrupted.

  • If you want to create a new file for each document instance, you must use the following file path format:

    file://C:\dir\file%tracking_id%.xml

Notes

  • For all transport types except Message Queuing, a prefix is automatically created for the address. This prefix is required and must not be deleted.

  • For the Message Queuing transport type, the following conditions must be met for a valid address:
    • Do not use the queue:// prefix in the address.

    • Use a format name, rather than a path. The following are valid format names:

      DIRECT=OS:<ServerName>\<QueueName>

      PUBLIC=<QueueName GUID>

      DIRECT=TCP:<IPAddress\QueueName>

      If you use the PUBLIC= format name, do not include the brackets with the message queue globally unique identifier (GUID).

      For more information about Message Queuing, go to the MSDN Online Library Web site (msdn.microsoft.com/library) and search on the keywords "Message Queuing."

  • For the File transport type, the following conditions must be met for a valid address:
    • The file path that you specify must exist. The file path is not created automatically, and you do not receive a warning that it does not exist.

    • You must specify a file name with an extension.

      An example of a valid file path is:

      file://C:\dir\file.xml

  • For the File transport type, you can include characters and symbols to dynamically modify the file name. The file name created by the server contains any static characters that you type into the Address box, along with the value of the symbol. For example, if you type file://C:\Orders\Invoice_%tracking_id%.xml in the Address box, the actual file name might appear as C:\Orders\Invoice_{12345678-90AB-CDEF-1234-567890ABCDEF}.

    The following table contains the symbols that you can use with the File transport type.

    Symbol | Description | Unique file name
    %datetime% | Date and time, in milliseconds, of the file creation. The time is based on Greenwich Mean Time (GMT) rather than local time. | No
    %document_name% | Name of the document definition used to process the source file. | No
    %server% | Host name of the server that processed the document. | No
    %src_filename% | Name of the file that is being submitted for processing. | No
    %tracking_id% | Globally unique tracking number. | Yes
    %uid% | Counter that increases over time, represented in milliseconds. This number is reset when the server is restarted. | No

  • The default setting for the file transport component is to append files. If you choose the File transport type with its default settings in a messaging port and use antivirus software on the server on which BizTalk Server 2002 is installed, and you send multiple files that have exactly the same name to the same file location, at the same time, BizTalk Server 2002 might stop responding and must be restarted. You can eliminate this problem by changing the default setting for the file transport component from Append to file to Overwrite file in the BizTalk SendLocalFile Properties dialog box. You also can eliminate this problem by creating a unique file for each document instance processed by using the file path format in the messaging port: file://C:\dir\file%tracking_id%.xml. For more information about overriding the append setting for the file transport component in the advanced properties of the channel, see Override messaging port defaults.

  • The default setting for the file transport component is to append files. If you choose the File transport type with its default settings and select an envelope with a reliable format in a messaging port, and then send multiple files to the same file location, at the same time, you might have unexpected parsing results. You can eliminate this problem by changing the default setting for the file transport component from Append to file to Overwrite file in the BizTalk SendLocalFile Properties dialog box. For more information about overriding the append setting for the file transport component in the advanced properties of the channel, see Override messaging port defaults.

  • The wildcard %src_filepath% exists in the transport dictionary, but is not functional.

Related Topics

Create messaging ports

Select an application integration component

Select a transport type

Set Messaging Port Properties

Set Transport Properties

Terminology map


Select an application integration component

  1. On the Destination Application or Destination Organization page of the Messaging Port Properties Wizard, in the Primary transport or Backup transport area, click Browse.

    The Primary Transport or Backup Transport dialog box appears.

  2. In the Transport type list, click Application Integration Component.

  3. To the right of the Component name box, click Browse.

    The Select a Component dialog box appears.

  4. In the Available components list, click a component and click OK.

To continue setting destination organization properties, go to Set destination organization properties.

Note

  • An application integration component (AIC) must be registered with BizTalk Server 2002 before it will be available in the Available components list. For more information, see Registering Custom Components.

Related Topics

Create messaging ports

Select a transport type

Set Messaging Port Properties

Set Transport Properties

Specify a transport address

Terminology map


Change the default SMTP Subject value

The default value for the Simple Mail Transfer Protocol (SMTP) Subject is <document_name>-<Tracking_ID>. This enables you to route documents based on the document definition name.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and click BizTalk Messaging Manager.

  2. In the Search for other items area, click Channels and click Search Now.

  3. Under Channel Name, click the channel for which you want to view the SMTP Subject and press ENTER.

    The Channel Properties Wizard opens.

  4. Click Next to advance through the wizard until you get to the Advanced Configuration page.

  5. On the Advanced Configuration page, click Advanced.

  6. In the Override Messaging Port Defaults dialog box, click Properties.

  7. In the Subject box, enter a new default value and click OK twice.

  8. Click Finish.

    The change is saved.

Note

  • If you create an Open Destination messaging port, the Override Messaging Port Defaults dialog box is unavailable. If you use SMTP as your transport service for open destination documents and interchanges, you can route the document based on the Tracking ID and the document definition name.


Set Envelope Delimiters

Delimiter properties specify which characters are used to separate data within an envelope and the documents of an interchange. Delimiters are required only for envelopes that use the X12 and EDIFACT formats. They are optional for envelopes that use a custom format.

Envelope delimiters are set when you select an envelope within a messaging port. The delimiters that are set for a messaging port apply only to that messaging port. Different delimiters can be set for the same envelope when it is used in a different messaging port. This section describes how to set delimiter properties.

The following procedures are covered in this section:

  • Set X12 delimiters

  • Set EDIFACT delimiters

  • Set custom delimiters

  • Terminology map


Set X12 delimiters

  1. On the Envelope Information page of the Messaging Port Properties Wizard, in the Envelope information area, select an envelope with an X12 format and click Delimiters.

    The X12 Delimiters dialog box appears.

  2. Enter delimiter values in either the Character or Hexadecimal box and click OK.

The following table describes the X12 delimiters.

Delimiter | Description
Component element separator | Specifies the character that is used to separate components of data within a composite data field. A composite data field is a field that consists of multiple subfields.
Element separator | Specifies the character that is used to separate data fields within a record.
Segment terminator | Specifies the character that is used to indicate the end of a record.

To continue setting destination organization properties, go to Set envelope information properties.

Note

  • You can type either one character in the Character box or two characters in the Hexadecimal box for each delimiter. The Hexadecimal box can be used to enter nonprinting character delimiters, such as the ENTER key.

Related Topics

Create messaging ports

Set custom delimiters

Set EDIFACT delimiters

Set Envelope Delimiters

Set envelope information properties

Set Messaging Port Properties

Terminology map


Set EDIFACT delimiters

  1. On the Envelope Information page of the Messaging Port Properties Wizard, in the Envelope information area, select an envelope with an EDIFACT format and click Delimiters.

    The EDIFACT Delimiters dialog box appears.

  2. Enter delimiter values in either the Character or Hexadecimal box and click OK.

The following table describes the EDIFACT delimiters.

Delimiter | Description
Component element separator | Specifies the character that is used to separate components of data within a composite data field. A composite data field is a field that consists of multiple subfields.
Element separator | Specifies the character that is used to separate data fields within a record.
Release indicator | Specifies the character that is used to indicate that the following character should not be evaluated as a delimiter.
Segment terminator | Specifies the character that is used to indicate the end of a record.

Notes

  • If you use EDIFACT release indicators, do not include release indicator characters in your data. Doing so might cause the data to exceed the physical character size limits for fields.

  • You can type either one character in the Character box or two characters in the Hexadecimal box for each delimiter. The Hexadecimal box can be used to enter nonprinting character delimiters, such as the ENTER key.

  • The EDIFACT decimal specification delimiter cannot be used.

To continue setting destination organization properties, go to Set envelope information properties.

Related Topics

Create messaging ports

Set custom delimiters

Set Envelope delimiters

Set envelope information properties

Set Messaging Port properties

Set X12 delimiters

Terminology map


Set custom delimiters

  1. On the Envelope Information page of the Messaging Port Properties Wizard, in the Envelope information area, select an envelope with a custom format and click Delimiters.

    The Custom Delimiters dialog box appears.

  2. Enter delimiter values in either the Character or Hexadecimal box and click OK.

The following table describes the custom delimiters.

Delimiter | Description
Subfield | Specifies the character that is used to separate components of data within a multipart data field.
Field | Specifies the character that is used to separate the data fields within a record.
Escape character | Specifies the character that is used to indicate that the following character should not be evaluated as a delimiter.
Record | Specifies the character that is used to indicate the end of a record.

Note

  • You can type either one character in the Character box or two characters in the Hexadecimal box for each delimiter. The Hexadecimal box can be used to enter nonprinting character delimiters, such as the ENTER key.

To continue setting destination organization properties, go to Set envelope information properties.

Related Topics

Create messaging ports

Set EDIFACT delimiters

Set Envelope delimiters

Set envelope information properties

Set Messaging Port properties

Set X12 delimiters

Terminology map


Terminology map

BizTalk Server uses different terms to describe various delimiters and escape characters for X12/EDIFACT standards. The following table lists terms that have similar meanings but are labeled differently in XML tools (such as BizTalk Editor) and BizTalk Messaging Manager components.

XML tools | BizTalk Messaging Manager
Record delimiter | Segment terminator
Field delimiter | Element separator
SubField delimiter | Component element separator
Escape character | Release indicator

Related Topics

Create messaging ports

Set custom delimiters

Set EDIFACT delimiters

Set Envelope delimiters

Set envelope information properties

Set Messaging Port Properties

Set X12 delimiters


Create and Manage Organizations

This section provides task-specific information about how to create and manage organizations. It is highly recommended that you review Understanding Organizations to fully understand organizations.

The following procedures are covered in this section:

  • Configure the home organization

  • Create organizations

  • Search for organizations

  • Edit organizations

  • Delete organizations

  • Set Organization Properties


Configure the home organization

  1. In BizTalk Messaging Manager, in the Search for other items area, click Organizations.

  2. In the Search for organizations area, select the Home organization check box and click Search Now.

  3. In the Organization Name list, double-click Home Organization.

    The Organization Properties dialog box appears.

  4. On the General tab, set the general organization properties.

    For more information, see Set general organization properties.

  5. Click the Identifiers tab and set the organization identifier properties.

    For more information, see Set Organization Identifier Properties.

  6. Click the Applications tab and set the application properties.

    For more information, see Set Application Properties.

  7. After you have set all the necessary home organization properties, click OK to close the Organization Properties dialog box.

Important

  • An organization identifier named Reliable Messaging Acknowledgement SMTP From Address is automatically created for the home organization. This identifier cannot be removed. You should not modify the name or qualifier for this identifier, but you can modify the value. The value specified for this identifier is used as the From address when sending reliable messaging receipts that use the SMTP transport protocol. For more information about reliable messaging receipts, see Processing Receipts Using Reliable Messaging.

  • The value specified for the organization identifier (Reliable Messaging Acknowledgement SMTP From Address) is also used as the From address when the address provided for an open messaging port is an SMTP address. For more information, see Openness.

Notes

  • You can rename the home organization at any time to any name that you want.

  • In BizTalk Messaging Manager, you can add applications only to the home organization.

Related Topics

Edit organizations

Search for organizations

Set Application Properties

Set Organization Properties

Understanding Organizations


Create organizations

  1. In BizTalk Messaging Manager, on the File menu, point to New and click Organization.

    The New Organization dialog box appears.

  2. On the General tab, set the general organization properties.

    For more information, see Set general organization properties.

  3. Click the Identifiers tab and set the organization identifier properties.

    For more information, see Set Organization Identifier Properties.

  4. After you have set all the necessary properties, click OK to close the New Organization dialog box.

Related Topics

Configure the home organization

Delete organizations

Edit organizations

Search for organizations

Set Organization Properties

Understanding Organizations


Search for organizations

  1. In BizTalk Messaging Manager, in the Search for other items area, click Organizations.

  2. Do one or more of the following:
    • To search for all organizations, clear all search criteria and click Search Now.

    • To search for organizations with a specific name, in the Search for organizations area, in the Organization name box, type the name of the organization that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for the home organization only, select the Home organization check box and click Search Now.

Notes

  • To clear the search criteria and search results, click Clear Search.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • You can use the following wildcard characters in the search criteria.
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Delete organizations

Edit organizations

Understanding Organizations


Edit organizations

  1. In BizTalk Messaging Manager, in the Organization Name list, click the organization that you want to edit.

    For information about searching for organizations, see Search for organizations.

  2. On the File menu, click Edit.

    The Organization Properties dialog box appears.

  3. On the General tab, edit any properties that you want to change.

    For more information, see Set general organization properties.

  4. Click the Identifiers tab and edit any organization identifier properties that you want to change.

    For more information, see Set Organization Identifier Properties.

  5. If you are editing the home organization, click the Applications tab and edit any application properties that you want to change.

    For more information, see Set Application Properties.

  6. After you have edited all the properties that you want to change, click OK to close the Organization Properties dialog box.

Important

  • An organization identifier named Reliable Messaging Acknowledgement SMTP From Address is automatically created for the home organization. This identifier cannot be removed. You should not modify the name or qualifier for this identifier, but you can modify the value. The value specified for this identifier is used as the From address when sending reliable messaging receipts that use the SMTP transport protocol. For more information about reliable messaging receipts, see Processing Receipts Using Reliable Messaging.

  • The value specified for the organization identifier (Reliable Messaging Acknowledgement SMTP From Address) is also used as the From address when the address provided for an open messaging port is an SMTP address. For more information, see Openness.

Note

  • In BizTalk Messaging Manager, you can add applications only to the home organization.

Related Topics

Create organizations

Delete organizations

Search for organizations

Understanding Organizations


Delete organizations

  1. In BizTalk Messaging Manager, in the Organization Name list, click the organization that you want to delete.

    For more information about searching for organizations, see Search for organizations.

  2. On the File menu, click Delete.

Notes

  • If an organization is used in a messaging port or a channel, you cannot delete it. You must first delete all channels and messaging ports that use the organization.

  • You cannot delete the home organization.

Related Topics

Create organizations

Edit organizations

Search for organizations

Understanding Organizations


Set Organization Properties

This section provides task-specific information about how to configure the properties of an organization.

The following procedures are covered in this section:

  • Set general organization properties

  • Set Organization Identifier Properties

  • Set Application Properties


Set general organization properties

  1. On the File menu, point to New and click Organization, or in the Organization Name list, double-click an organization.

    The Organization dialog box appears.

  2. On the General tab, in the Organization name box, type a unique name for the organization.

  3. In the Comments box, type any comments that you want for the organization.

Related Topics

Configure the home organization

Create organizations

Edit organizations

Set Organization Properties


Set Organization Identifier Properties

Organization identifiers are used to uniquely identify organizations. An organization can have more than one organization identifier, but each identifier must be unique for that organization.

When you create a new organization, an organization identifier named Organization is automatically created. The qualifier for this identifier is OrganizationName, and the value is the name that you give the organization. This server uses this organization identifier as the default identifier, unless you create additional identifiers and designate one of them as the default identifier.

The following procedures are covered in this section:

  • Add organization identifiers

  • Edit organization identifiers

  • Remove organization identifiers

Related Topics

Configure the home organization

Create organizations

Edit organizations

Organization Identifiers

Set Organization Properties


Add organization identifiers

  1. On the File menu, point to New and click Organization, or in the Organization Name list, double-click an organization.

    The Organization dialog box appears.

  2. Click the Identifiers tab and click Add.

    The New Identifier dialog box appears.

  3. In the Name area, complete one of the following steps:
    • Click Standard and click a name in the list.

    • Click Custom and type a unique name in the box. Then, in the Qualifier box, type a qualifier for the identifier.
  4. In the Value box, type a value for the identifier.

  5. If you want to set this identifier as the default identifier for the organization, select the Set as default check box; otherwise, make sure that the check box is cleared.

  6. Click OK to close the New Identifier dialog box.

Important

  • An organization identifier named Reliable Messaging Acknowledgement SMTP From Address is automatically created for the home organization. This identifier cannot be removed. You should not modify the name or qualifier for this identifier, but you can modify the value. The value specified for this identifier is used as the From address when sending reliable messaging receipts that use the SMTP transport protocol. For more information, see Processing Receipts Using Reliable Messaging.

  • The value specified for the organization identifier (Reliable Messaging Acknowledgement SMTP From Address) is also used as the From address when the address provided for an open messaging port is an SMTP address. For more information, see Openness.

Notes

  • Only one identifier can be designated as the default identifier for an organization. The default identifier is used to identify an organization unless you specify another organization identifier in a channel or messaging port.

  • When you create a new organization, an organization identifier named Organization is automatically created. The qualifier for this identifier is OrganizationName, and the value is the name of the organization. You can create additional identifiers, but this identifier cannot be modified or removed.

  • When you create an organization identifier for use with EDIFACT envelopes, the qualifier must not exceed 4 characters and the value must not exceed 35 characters.

  • When you create an organization identifier for use with X12 envelopes, the qualifier must not exceed 2 characters and the value must not exceed 15 characters.

Related Topics

Configure the home organization

Create organizations

Edit organization identifiers

Edit organizations

Organization Identifiers

Remove organization identifiers

Set Organization Identifier Properties


Edit organization identifiers

  1. On the File menu, point to New and click Organization, or in the Organization Name list, double-click an organization.

    The Organization dialog box appears.

  2. Click the Identifiers tab.

  3. In the Organization identifiers list, click the organization identifier that you want to edit and click Edit.

    The Identifier Properties dialog box appears.

  4. In the Name area, complete one of the following steps:
    • Click Standard and click a name in the list.

    • Click Custom and type a unique name in the box. Then, in the Qualifier box, type a qualifier for the identifier.
  5. In the Value box, type a value for the identifier.

  6. If you want to set this identifier as the default identifier for the organization, select the Set as default check box; otherwise, make sure that the check box is cleared.

  7. Click OK to close the Identifier Properties dialog box.

Important

  • An organization identifier named Reliable Messaging Acknowledgement SMTP From Address is automatically created for the home organization. You should not modify the name or qualifier for this identifier, but you can modify the value. This identifier cannot be removed. The value for this identifier is used as the From address when sending reliable messaging receipts that use the SMTP transport protocol. For more information, see Processing Receipts Using Reliable Messaging.

  • The value specified for the organization identifier (Reliable Messaging Acknowledgement SMTP From Address) is also used as the From address when the address provided for an open messaging port is an SMTP address. For more information, see Openness.

Notes

  • Only one identifier can be designated as the default identifier for an organization. The default identifier is used to identify an organization unless you specify another organization identifier in a channel or messaging port.

  • When you create a new organization, an organization identifier named Organization is automatically created. The qualifier for this identifier is OrganizationName, and the value is the name of the organization. You can create additional identifiers, but this identifier cannot be modified or removed.

  • When you create an organization identifier for use with EDIFACT envelopes, the qualifier must not exceed 4 characters and the value must not exceed 35 characters.

  • When you create an organization identifier for use with X12 envelopes, the qualifier must not exceed 2 characters and the value must not exceed 15 characters.

Related Topics

Add organization identifiers

Configure the home organization

Create organizations

Edit organizations

Organization Identifiers

Remove organization identifiers

Set Organization Identifier Properties


Remove organization identifiers

  1. On the File menu, point to New and click Organization, or in the Organization Name list, double-click an organization.

    The Organization dialog box appears.

  2. Click the Identifiers tab.

  3. In the Organization identifiers list, click the identifier that you want to remove and click Remove.

Notes

  • The designated default organization identifier cannot be removed until you have designated another identifier as the default identifier.

  • The organization identifier named Organization is automatically created when you create an organization. This organization identifier cannot be removed.

Related Topics

Add organization identifiers

Configure the home organization

Create organizations

Edit organization identifiers

Edit organizations

Organization Identifiers

Set Organization Identifier Properties


Set Application Properties

In BizTalk Messaging Manager, you can add applications only to the home organization. The applications that you create enable you to identify and track the flow of documents between BizTalk Server 2002 and actual internal applications within your business. You can designate an application of the home organization as a source application in a channel or a destination application in a messaging port.

The home organization can have any number of applications. Each application name must be unique.

The following procedures are covered in this section:

  • Add applications

  • Edit applications

  • Remove applications

Related Topics

Configure the home organization

Edit organizations

Set Organization Properties


Add applications

  1. In BizTalk Messaging Manager, in the Search for other items area, click Organizations.

  2. In the Search for organizations area, select the Home organization check box and click Search Now.

  3. In the Organization Name list, double-click Home Organization.

    The Organization Properties dialog box appears.

  4. On the Applications tab, click Add.

    The New Application dialog box appears.

  5. In the Application name box, type a unique name for the application and click OK.

Note

  • In BizTalk Messaging Manager, you can add, edit, and remove applications only for the home organization.

Related Topics

Configure the home organization

Edit applications

Edit organizations

Remove applications

Set Application Properties


Edit applications

  1. In BizTalk Messaging Manager, in the Search for other items area, click Organizations.

  2. In the Search for organizations area, select the Home organization check box and click Search Now.

  3. In the Organization Name list, double-click Home Organization.

    The Organization Properties dialog box appears.

  4. On the Applications tab, in the Applications list, click the application that you want to edit and click Edit.

    The Application Properties dialog box appears.

  5. In the Application name box, type a unique name for the application and click OK.

Note

  • In BizTalk Messaging Manager, you can add, edit, and remove applications only for the home organization.

Related Topics

Add applications

Configure the home organization

Edit organizations

Remove applications

Set Application Properties


Remove applications

  1. In BizTalk Messaging Manager, in the Search for other items area, click Organizations.

  2. In the Search for organizations area, select the Home organization check box and click Search Now.

  3. In the Organization Name list, double-click Home Organization.

    The Organization Properties dialog box appears.

  4. On the Applications tab, in the Applications list, click the application that you want to remove and click Remove.

Note

  • In BizTalk Messaging Manager, you can add, edit, and remove applications only for the home organization.

Related Topics

Add applications

Configure the home organization

Edit organizations

Set Application Properties


Create and Manage Document Definitions

This section provides task-specific information about how to create and manage document definitions. It is highly recommended that you review Understanding Document Definitions to fully understand document definitions.

The following procedures are covered in this section:

  • Create document definitions

  • Search for document definitions

  • Edit document definitions

  • Delete document definitions

  • Set Document Definition Properties


Create document definitions

  1. In BizTalk Messaging Manager, on the File menu, point to New and click Document Definition.

    The New Document Definition dialog box appears.

  2. On the General tab, set the general properties.

    For more information, see Set general document-definition properties.

  3. Click the Global Tracking tab and set the tracking properties.

    For more information, see Set Global Tracking Properties.

  4. Click the Selection Criteria tab and set the selection criteria properties.

    For more information, see Set Selection Criteria Properties.

  5. After you have set all the properties that you want, click OK to close the New Document Definition dialog box.

Notes

  • You can select tracking fields only from a schema created in or imported into BizTalk Editor.

  • You cannot name a document definition Reliable Message Acknowledgement Channel or BizTalk Canonical Receipt, which are reserved system names.

  • You cannot specify global tracking fields for the document definition unless you select a specification.

  • When you select a document definition in a channel, you can override the global tracking fields for that channel by selecting different specification fields to track. For more information, see Select specification fields in a channel.

  • When you save a document definition that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Delete document definitions

Edit document definitions

Search for document definitions

Understanding Document Definitions


Search for document definitions

  1. In BizTalk Messaging Manager, in the Search for other items area, click Document Definitions.

  2. To search for all document definitions, clear all search criteria and click Search Now.

    –Or–

    To search for a document definition with a specific name, in the Search for document definitions area, in the Document definition name box, type the name of the document definition that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

Notes

  • To clear the search criteria and search results, click Clear Search.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • You can use the following wildcard characters in the search criteria:
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Delete document definitions

Edit document definitions

Understanding Document Definitions


Edit document definitions

  1. In BizTalk Messaging Manager, in the Document Definition Name list, click the document definition that you want to edit.

    For more information about searching for document definitions, see Search for document definitions.

  2. On the File menu, click Edit.

    The Document Definition Properties dialog box appears.

  3. On the General tab, edit the general properties.

    For more information, see Set general document-definition properties.

  4. Click the Global Tracking tab and edit the tracking properties.

    For more information, see Set Global Tracking Properties.

  5. Click the Selection Criteria tab and edit the selection criteria properties.

    For more information, see Set Selection Criteria Properties.

  6. After you have edited all the properties that you want to change, click OK to close the Document Definition Properties dialog box.

Notes

  • You cannot name a document definition Reliable Message Acknowledgement Channel or BizTalk Canonical Receipt, which are reserved system names.

  • You cannot specify global tracking fields for the document definition unless you select a specification.

  • When you save a document definition that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create document definitions

Delete document definitions

Search for document definitions

Understanding Document Definitions


Delete document definitions

  1. In BizTalk Messaging Manager, in the Document Definition Name list, click the document definition that you want to delete.

    For more information about searching for document definitions, see Search for document definitions.

  2. On the File menu, click Delete.

Note

  • If a document definition is used in a channel, you cannot delete it. You must first delete all channels that use the document definition.

Related Topics

Create document definitions

Edit document definitions

Search for document definitions

Understanding Document Definitions


Set Document Definition Properties

This section provides task-specific information about how to configure the properties of a document definition.

The following procedures are covered in this section:

  • Set general document-definition properties

  • Select a document specification

  • Set Global Tracking Properties

  • Set Selection Criteria Properties


Set general document-definition properties

  1. In the New Document Definition or Document Definition Properties dialog box, click the General tab.

  2. In the Document definition name box, type a unique name for the document definition.

  3. Select the Document specification check box.

  4. Click Browse to select a document specification.

    For more information, see Select a document specification.

Notes

  • A document specification is optional; however, in most cases you should select one. If you do not select a specification:
    • The data that you process is not translated into XML on the inbound side or from XML on the outbound side.

    • The data is not validated against a specification to ensure that it does not contain errors.

    • You cannot transform the structure or format of the data by using a map in a channel.

    • You cannot specify global tracking fields for the document definition.
  • If you are processing data that you do not want to translate, transform, or validate, such as a binary file, you should not select a document specification.

  • If you enter a non-BizTalk Server document specification, you cannot select tracking fields on the Global Tracking tab.

Related Topics

Create document definitions

Edit document definitions

Set Document Definition Properties

Understanding Document Definitions


Select a document specification

  1. In the New Document Definition or Document Definition Properties dialog box, click the General tab.

  2. Select the Document specification check box and click Browse.

    The Select a Document Specification from the WebDAV Repository dialog box appears.

  3. In the Server box, do one of the following if you want to change the server:
    • Click a server in the list.

    • Type the name of a server and press ENTER.
  4. Double-click the folder that contains the specification that you want to open, and double-click the file.

Important

  • The first time that you open any WebDAV repository dialog box, the WebDAV repository on the local server is selected, even if BizTalk Messaging Manager is connected to a database on a remote server. If you browse to a WebDAV repository on a remote server, the default changes to that server until you select a new WebDAV repository. The default server for all WebDAV repository dialog boxes is the last server to which a connection was made.

Notes

  • If you select http://localhost as the server, BizTalk Messaging Manager automatically converts it to the local computer name.

  • If a document definition is used as the inbound document definition in a channel for an open messaging port, and the destination information is provided in the document, the document definition must reference a specification that is properly configured. For more information about how to configure a document specification to process documents for an open messaging port, see Set dictionary properties.

  • A document specification is optional; however, in most cases you should select one. If you do not select a specification:
    • The data that you process is not translated into XML on the inbound side or from XML on the outbound side.

    • The data is not validated against a specification to ensure that it does not contain errors.

    • You cannot transform the structure or format of the data by using a map in a channel.

    • You cannot specify global tracking fields for the document definition.
  • A document specification is not required if you want to use the document definition in a pass-through submission.

  • If a document specification, envelope specification, or map is modified with BizTalk Editor or BizTalk Mapper and then saved to the repository, the specification or map must be reloaded into BizTalk Messaging Manager so the server can recognize the changes and the database content can be updated.

  • You might experience some delay the first time that you connect to a WebDAV repository on a remote server.

  • When you save a document definition that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create document definitions

Edit document definitions

Set Document Definition Properties

Understanding Document Definitions


Set Global Tracking Properties

On the Global Tracking tab, the Specification fields list provides a tree view of the specification that you selected for the document definition. You can expand this list to view the fields in the specification and designate a limited number of fields to log to the Tracking database.

When the document definition is selected as the inbound document definition for a channel, these fields are tracked for each instance of a document that is processed by that channel. These fields are referred to as global tracking fields. When you select a document definition in a channel, you have the option of overriding the global tracking fields by selecting different specification fields to track for each document instance processed by that channel only.

This section describes how to select specification fields for a document definition.

The following procedures are covered in this section:

  • Select specification fields in a document definition

  • Remove specification fields in a document definition

Related Topics

Tracking Document Data Fields

Understanding Document Definitions


Select specification fields in a document definition

  1. In the New Document Definition or Document Definition Properties dialog box, click the Global Tracking tab.

  2. In the Specification fields list, click the expand indicator (+) next to any record, or double-click the record, to expand the view.

  3. Select a specification field that you want to add to the Fields to track list, and then complete one of the following procedures:
    To add the field as | Follow this procedure
    Integer | Click Integer. You can add two fields as integers.
    Real | Click Real. You can add two fields as real numbers.
    Date | Click Date. You can add two fields as dates.
    Text | Click Text. You can add two fields as text.
    Custom | Click Custom. You can add unlimited fields as a custom type. The fields are stored as an XML concatenated string with tags for each field.

Notes

  • To select a specification field to track as an integer, real, or date data type, the field must have that data type assigned in the specification. For more information about assigning a data type to a specification field, see Set declaration properties.

  • Specification fields without a data type assigned in the specification can be tracked only as a text or custom data type.

  • If a specification field that you want to track has a character data type, you can only track that field as a custom type.

  • When you select a document definition in a channel, you can override the global tracking fields for that channel by selecting different specification fields to track. For more information, see Select specification fields in a channel.

Related Topics

Create document definitions

Edit document definitions

Remove specification fields in a document definition

Set Document Definition Properties

Set Global Tracking Properties

Tracking Document Data Fields

Understanding Document Definitions


Remove specification fields from a document definition

  1. In the New Document Definition or Document Definition Properties dialog box, click the Global Tracking tab.

  2. In the Fields to track list, select the specification field or fields that you want to remove and click Remove.

Note

  • When you remove a field from the list of fields to track, it is removed only from the list in this document definition; it is not removed from the specification.

Related Topics

Create document definitions

Edit document definitions

Select specification fields in a document definition

Set Document Definition Properties

Set Global Tracking Properties

Tracking Document Data Fields

Understanding Document Definitions


Set Selection Criteria Properties

Selection criteria are a unique set of name-value pairs that BizTalk Server uses only to process EDI documents. For inbound X12 or EDIFACT documents, the server uses selection criteria to uniquely identify and select a document definition because no document definition name is available within individual EDI documents.

For outbound X12 or EDIFACT documents, selection criteria are used to create the group header information.

The following procedures are covered in this section:

  • Add selection criteria

  • Edit selection criteria

  • Remove selection criteria

Related Topics

Understanding Document Definitions

Understanding Selection Criteria


Add selection criteria

  1. In the New Document Definition or Document Definition Properties dialog box, click the Selection Criteria tab and click Add.

    The New Name and Value dialog box appears.

  2. In the Name box, type a name for the selection criteria.

  3. In the Value box, type a value for the selection criteria and click OK.

Important

  • For BizTalk Server 2002 to match the selection criteria values to the corresponding header elements of inbound interchanges, and to insert the values into the correct header elements of outbound interchanges, you must type the selection criteria names exactly as shown in the following tables.

    X12 header elements
    Name | Requirement | GS element
    functional_identifier | Mandatory | GS01
    application_sender_code | Mandatory | GS02
    application_receiver_code | Mandatory | GS03
    standards_version | Mandatory | GS08

    EDIFACT header elements
    Name | Requirement | UNH element | UNG element
    functional_identifier | Mandatory | S009, 0065 | 0038
    application_sender_code | Optional | Not used | S006, 0040
    application_receiver_code | Optional | Not used | S007, 0044
    standards_version_type | Mandatory | S009, 0052 | S008, 0052
    standards_version_value | Mandatory | S009, 0054 | S008, 0054

  • For an outbound EDIFACT interchange, a message header (UNH) is always created. If you specify an application_sender_code and an application_receiver_code, a group header (UNG) is also created.

  • The set of selection criteria name-value pairs that you use for each document definition must be unique across all document definitions.

Related Topics

Create document definitions

Edit document definitions

Edit selection criteria

Remove selection criteria

Set Document Definition Properties

Set Selection Criteria Properties

Understanding Document Definitions

Understanding Selection Criteria


Edit selection criteria

  1. In the New Document Definition or Document Definition Properties dialog box, click the Selection Criteria tab.

  2. In the Selection criteria list, click the selection criterion that you want to edit and click Edit.

    The Name and Value Properties dialog box appears.

  3. In the Name box, type a name for the selection criteria.

  4. In the Value box, type a value for the selection criteria and click OK.

Important

  • For BizTalk Server 2002 to match the selection criteria values to the corresponding header elements of inbound interchanges, and to insert the values into the correct header elements of outbound interchanges, you must type the selection criteria names exactly as shown in the following tables.

    X12 header elements
    Name | Requirement | GS Element
    functional_identifier | Mandatory | GS01
    application_sender_code | Mandatory | GS02
    application_receiver_code | Mandatory | GS03
    standards_version | Mandatory | GS08

    EDIFACT header elements
    Name | Requirement | UNH element | UNG element
    functional_identifier | Mandatory | S009, 0065 | 0038
    application_sender_code | Optional | Not used | S006, 0040
    application_receiver_code | Optional | Not used | S007, 0044
    standards_version_type | Mandatory | S009, 0052 | S008, 0052
    standards_version_value | Mandatory | S009, 0054 | S008, 0054

  • For an outbound EDIFACT interchange, a message header (UNH) is always created. If you specify an application_sender_code and an application_receiver_code, a group header (UNG) is also created.

  • The set of selection criteria name-value pairs that you use for each document definition must be unique across all document definitions.

Related Topics

Add selection criteria

Remove selection criteria

Set Selection Criteria Properties

Understanding Document Definitions

Understanding Selection Criteria


Remove selection criteria

  1. In the Document Definition Properties dialog box, click the Selection Criteria tab.

  2. In the Selection criteria list, click the criterion that you want to remove and click Remove.

Related Topics

Add selection criteria

Edit selection criteria

Set Selection Criteria Properties

Understanding Document Definitions

Understanding Selection Criteria


Create and Manage Envelopes

This section provides task-specific information about how to create and manage envelopes. It is highly recommended that you review Understanding Envelopes to fully understand envelopes.

The following procedures are covered in this section:

  • Create envelopes

  • Search for envelopes

  • Edit envelopes

  • Delete envelopes

  • Select an envelope specification


Create envelopes

  1. In BizTalk Messaging Manager, on the File menu, point to New and click Envelope.

    The New Envelope dialog box appears.

  2. In the Envelope name box, type a unique name for the envelope.

  3. In the Envelope format list, click one of the following envelope formats:
    • CUSTOM XML

      To enable Microsoft BizTalk Server 2002 to process inbound interchanges with a custom XML format, you must create an envelope with a custom XML format and a specification reference. However, when you submit custom XML interchanges, you do not need to specify the envelope name in the submit call parameters. BizTalk Server 2002 is able to locate the appropriate envelope without a name reference.

    • X12

      You do not need to create an envelope with an X12 format to enable BizTalk Server 2002 to process inbound interchanges with an X12 format, and you do not need to specify the envelope name in the submit call parameters.

    • EDIFACT

      You do not need to create an envelope with an EDIFACT format to enable BizTalk Server 2002 to process inbound interchanges with an EDIFACT format, and you do not need to specify the envelope name in the submit call parameters.

    • FLATFILE

      To enable BizTalk Server 2002 to process inbound interchanges with a flat-file format, you must create an envelope with a flat-file format. When you submit inbound flat-file documents, you must specify the envelope name in the submit call parameters. For more information, see Submitting.

    • CUSTOM

      To enable BizTalk Server 2002 to process inbound interchanges with a custom format, a format not supported directly by BizTalk Server, you must create a custom parser component. You need to create an envelope only if the custom parser requires one. For more information, see Parsers.

      To enable BizTalk Server to process outbound interchanges with a custom format, you must create an envelope with a custom format and select the envelope in a messaging port. You also must create and register a custom serializer component. For more information, see Serializers. You can configure the custom serializer in the channel on the Advanced Configuration page of the Channel Wizard. For more information, see Set advanced configuration properties.

    • RELIABLE

      You do not need to create an envelope with a reliable format to enable BizTalk Server 2002 to process inbound interchanges with a reliable format, and you do not need to specify the envelope name in the submit call parameters.

      The reliable format processes envelopes that are compliant with BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Web site (www.microsoft.com/biztalk/).

      If you choose the reliable format, you also must configure the Reliable messaging reply-to URL address in the BizTalk Server Group Properties dialog box. For more information, see Configure general properties for a server group.

  4. If you choose the custom XML, flat-file, or custom format, you can select a specification for the envelope. For more information, see Select an envelope specification.

Notes

  • To enable BizTalk Server 2002 to process outbound interchanges in any format, you must create an envelope.

  • If you choose the custom XML format and you do not select a specification, the envelope format defaults to the reliable format.

  • When processing envelopes that are compliant with BizTalk Framework 2.0, BizTalk Server 2002 should be considered the endpoint with regard to the expiration time. When BizTalk Framework 2.0–compliant documents are submitted to BizTalk Server, either from an application or a trading partner, the following fields are overwritten if present, or created if absent:
    • In the properties subsection:

      <prop:identity>

      <prop:sentAt>

      <prop:expiresAt>

    • In the receipt information subsection:

      <sendTo>

      <address>

      <sendReceiptBy>

  • If you change the envelope format and you have selected a specification, you also might need to select a different specification.

  • When you save an envelope that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Delete envelopes

Edit envelopes

Search for envelopes

Understanding Envelopes


Search for envelopes

  1. In BizTalk Messaging Manager, in the Search for other items area, click Envelopes.

  2. Do one or more of the following:
    • To search for all envelopes, clear all search criteria and click Search Now.

    • To search for an envelope with a specific name, in the Search for envelopes area, in the Envelope name box, type the name of the envelope that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for envelopes of a specific format, in the Format list, click a format and click Search Now.

Notes

  • You can set more than one search criteria before clicking Search Now.

  • To clear the search criteria and search results, click Clear Search.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • You can use the following wildcard characters in the search criteria:
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Delete envelopes

Edit envelopes

Understanding Envelopes


Edit envelopes

  1. In BizTalk Messaging Manager, in the Envelope Name list, click the envelope that you want to edit.

    For information about searching for envelopes, see Search for envelopes.

  2. On the File menu, click Edit.

    The Envelope Properties dialog box appears.

  3. In the Envelope name box, type a unique name for the envelope.

  4. In the Envelope format list, click one of the following envelope formats:
    • CUSTOM XML

      To enable BizTalk Server 2002 to process inbound interchanges with a custom XML format, you must create an envelope with a custom XML format and a specification reference. However, when you submit custom XML interchanges, you do not need to specify the envelope name in the submit call parameters. BizTalk Server is able to locate the appropriate envelope without a name reference.

    • X12

      You do not need to create an envelope with an X12 format to enable BizTalk Server 2002 to process inbound interchanges with an X12 format, and you do not need to specify the envelope name in the submit call parameters.

    • EDIFACT

      You do not need to create an envelope with an EDIFACT format to enable BizTalk Server 2002 to process inbound interchanges with an EDIFACT format, and you do not need to specify the envelope name in the submit call parameters.

    • FLATFILE

      To enable BizTalk Server 2002 to process inbound interchanges with a flat-file format, you must create an envelope with a flat-file format. When you submit inbound flat-file documents, you must specify the envelope name in the submit call parameters. For more information, see Submitting.

    • CUSTOM

      To enable BizTalk Server 2002 to process inbound interchanges with a custom format, a format not supported directly by BizTalk Server, you might need to create an envelope. However, you must create a custom parser component to process these interchanges, which might require an envelope. For more information, see Parsers.

      To enable BizTalk Server to process outbound interchanges with a custom format, you must create an envelope with a custom format and select the envelope in a messaging port. You also must create and register a custom serializer component. For more information, see Serializers. You can configure the custom serializer in the channel on the Advanced Configuration page of the Channel Wizard. For more information, see Set advanced configuration properties.

    • RELIABLE

      You do not need to create an envelope with a reliable format to enable BizTalk Server 2002 to process inbound interchanges with a reliable format, and you do not need to specify the envelope name in the submit call parameters.

      The reliable format processes envelopes that are compliant with BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Web site (www.microsoft.com/biztalk/).

      If you choose the reliable format, you also must configure the Reliable messaging reply-to URL address in the BizTalk Server Group Properties dialog box. For more information, see Configure general properties for a server group.

  5. If you choose the custom XML, flat-file, or custom format, you can select a specification for the envelope. For more information, see Select an envelope specification.

Important

  • If you create an envelope with the reliable format and select that envelope in a messaging port, you also must configure the Reliable messaging reply-to URL address in the BizTalk Server Group Properties dialog box. For more information, see Configure general properties for a server group.

Notes

  • To enable BizTalk Server 2002 to process outbound interchanges in any format, you must create an envelope.

  • If you choose the custom XML format and you do not select a specification, the envelope format defaults to the reliable format.

  • When processing envelopes that are compliant with BizTalk Framework 2.0, BizTalk Server 2002 should be considered the endpoint with regard to the expiration time. When BizTalk Framework 2.0–compliant documents are submitted to BizTalk Server, either from an application or a trading partner, the following fields are overwritten if present, or created if absent:
    • In the properties subsection:

      <prop:identity>

      <prop:sentAt>

      <prop:expiresAt>

    • In the receipt information subsection:

      <sendTo>

      <address>

      <sendReceiptBy>

  • If you change the envelope format and you have selected a specification, you also might need to select a different specification.

  • When you save an envelope that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create envelopes

Delete envelopes

Search for envelopes

Understanding Envelopes


Delete envelopes

  1. In BizTalk Messaging Manager, in the Envelope Name list, click the envelope that you want to delete.

    For more information about searching for envelopes, see Search for envelopes.

  2. On the File menu, click Delete.

Note

  • If an envelope is used in a messaging port, you cannot delete it. You must first delete all messaging ports that use the envelope.

Related Topics

Create envelopes

Edit envelopes

Search for envelopes

Understanding Envelopes


Select an envelope specification

  1. In the New Envelope or Envelope Properties dialog box, select the Envelope specification check box and click Browse.

    The Select an Envelope Specification from the WebDAV Repository dialog box appears.

  2. In the Server box, do one of the following if you want to change the server:
    • Click a server in the list.

    • Type the name of a server and press ENTER.
  3. Double-click the folder that contains the specification that you want to open, click the specification, and then click Open.

Important

  • The first time that you open any WebDAV repository dialog box, the WebDAV repository on the local server is selected, even if your BizTalk Messaging Manager is connected to a database on a remote server. If you browse to a WebDAV repository on a remote server, the default changes to that server until you select a new WebDAV repository. The default server for all WebDAV repository dialog boxes is the last server to which a connection was made.

Notes

  • If you select http://localhost as the server, BizTalk Messaging Manager automatically converts it to the local computer name.

  • If you choose the custom XML format, you can select a specification for the envelope. If you do not select a specification, the envelope format defaults to the reliable format that complies with BizTalk Framework 2.0. For more information about BizTalk Framework 2.0, go to the Microsoft BizTalk Web site (www.microsoft.com/biztalk/).

  • If you choose the flat-file format, you can select a specification for the envelope. You must select a specification if the envelope is used for opening inbound interchanges. A specification is not required if the envelope is used for creating outbound interchanges.

  • If a document specification, envelope specification, or map is modified with BizTalk Editor or BizTalk Mapper and then saved to the repository, the specification or map must be reloaded into BizTalk Messaging Manager so the server can recognize the changes and the database content can be updated.

  • If you choose a custom format, you can select a specification for the envelope. The custom parser or serializer that you create determines the need for a specification.

    To use the custom format, you also must:

    • Create a custom parser component for opening inbound interchanges with this custom format. For more information, see Parsers.

    • Create and configure a custom serializer component for creating outbound interchanges with this custom format. For more information, see Serializers.

    • Configure the custom serializer component using the messaging port override properties in the Channel Wizard. For more information, see Override messaging port defaults.
  • When you save an envelope that references a specification that is outside your local domain, you might receive an error. If you receive an error, download and configure the WinHTTP proxy utility. To download the utility, go to the Microsoft MSDN Web site (msdn.microsoft.com/downloads/default.asp) and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

Related Topics

Create envelopes

Edit envelopes

Search for envelopes

Understanding Envelopes


Use Distribution Lists

This section provides task-specific information about how to use distribution lists. It is highly recommended that you review Understanding Distribution Lists to fully understand distribution lists.

The following procedures are covered in this section:

  • Create distribution lists

  • Search for distribution lists

  • Edit distribution lists

  • Delete distribution lists


Create distribution lists

  1. In BizTalk Messaging Manager, on the File menu, point to New and click Distribution List.

    The New Distribution List dialog box appears.

  2. In the Distribution list name box, type a unique name for the distribution list.

  3. In the Available messaging ports list, select the messaging ports that you want to include and click Add.

    The selected messaging ports are added to the Selected messaging ports list.

  4. In the Selected messaging ports list, select any messaging ports that you do not want to include and click Remove.

  5. After you have set all the necessary properties, click OK to close the New Distribution List dialog box.

Notes

  • When you remove a messaging port from a distribution list, it is removed only from the distribution list; it is not removed from the database.

  • A distribution list must contain at least one messaging port.

  • Open messaging ports cannot be added to a distribution list.

  • To be functional, a distribution list requires at least one channel. For more information about channels, see Create and Manage Channels.

Related Topics

Delete distribution lists

Edit distribution lists

Search for distribution lists

Understanding Distribution Lists


Search for distribution lists

  1. In BizTalk Messaging Manager, in the Search for other items area, click Distribution lists.

  2. Do one or more of the following:
    • To search for all distribution lists, clear all search criteria and click Search Now.

    • To search for a distribution list with a specific name, in the Search for distribution lists area, in the Distribution list name box, type the name of the distribution list that you want to find and click Search Now. You can enter an incomplete name and the search returns all possible names that match the incomplete name entry.

    • To search for distribution lists that contain a specific messaging port, in the Containing messaging port list, type the name of the messaging port and click Search Now.

Notes

  • To clear the search criteria and search results, click Clear Search.

  • If you have a large number of objects for which to search, it might take several minutes to return all the objects. You can narrow the objects returned in a search by using selection criteria.

  • The default number of items returned in a search is 500. You can adjust this number. For more information, see Set server connection options.

  • You can use the following wildcard characters in the search criteria:
    Wildcard character | Description | Example
    % Any string of zero or more characters. The entry '%open%' finds all names with the word 'open' anywhere in the name.
    _ (underscore) | Any single character. | The entry '_ean' finds four-letter names that end with ean (Dean, Sean, and so on).
    [ ] Any single character within the specified range ([a-f]) or set ([abcdef]). The entry '[C-P]arsen' finds names ending with arsen and beginning with any single character between C and P (Carsen, Larsen, and so on).
    [^] Any single character not within the specified range ([^a-f]) or set ([^abcdef]). The entry 'de[^s]%' finds all names beginning with de and where the following letter is not s.

Related Topics

Create distribution lists

Delete distribution lists

Edit distribution lists

Understanding Distribution Lists


Edit distribution lists

  1. In BizTalk Messaging Manager, in the Distribution List Name list, click the distribution list that you want to edit.

    For information about searching for distribution lists, see Search for distribution lists.

  2. On the File menu, click Edit.

    The Distribution List Properties dialog box appears.

  3. In the Distribution list name box, type a unique name for the distribution list.

  4. In the Available messaging ports list, select the messaging ports that you want to include and, to add them to the Selected messaging ports list, click Add.

  5. In the Selected messaging ports list, select any messaging ports that you do not want to include and click Remove.

  6. After you have set all the necessary properties, click OK to close the Distribution List Properties dialog box.

Notes

  • When you remove a messaging port from a distribution list, it is removed only from the distribution list; it is not removed from the database.

  • A distribution list must contain at least one messaging port.

  • Open messaging ports cannot be added to a distribution list.

Related Topics

Create distribution lists

Delete distribution lists

Search for distribution lists

Understanding Distribution Lists


Delete distribution lists

  1. In BizTalk Messaging Manager, in the Distribution List Name list, click the distribution list that you want to delete.

    For more information about searching for distribution lists, see Search for distribution lists.

  2. On the File menu, click Delete.

Notes

  • You cannot delete a distribution list until all channels that are associated with the distribution list have been deleted.

  • You can search for channels associated with a distribution list by right-clicking the distribution list and clicking Find Channels.

Related Topics

Create distribution lists

Search for distribution lists

Understanding Distribution Lists


Creating Specifications and Mapping Data

Microsoft® BizTalk™ Server 2002 provides tools with which you can define the structure of a document and map data from one format to another. These tools are based on Extensible Markup Language (XML) and related standards, such as Extensible Stylesheet Language (XSL) Transformation (XSLT), and they provide the essential data translation necessary for an application-integration server.

Using BizTalk Editor, you can create specifications that are based on industry standards and common schemas, or you can create specifications that are unique to your organization.

Using BizTalk Mapper, you can create a map between the records and fields of two different specifications. The server uses the map to process and translate data into formats that can be shared within your own organization or with your partner organizations.

The following topics are covered in this section:

  • Using BizTalk Editor

  • Using BizTalk Mapper

  • Troubleshooting BizTalk Editor and BizTalk Mapper


Using BizTalk Editor

Microsoft® BizTalk™ Editor is a tool with which you can create, edit, and manage specifications. BizTalk Editor uses XML-Data Reduced (XDR) syntax, which provides a common vocabulary to handle overlaps between syntactic, database, and conceptual schemas.

BizTalk Editor creates specifications by interpreting the properties of records and fields that are contained in a file. Specifications represent the structured data as Extensible Markup Language (XML), regardless of the original format. In addition, specifications that you create or modify in BizTalk Editor provide common data descriptions that BizTalk Mapper can use to transform data across dissimilar formats. The specifications provide data portability across business processes. A specification created using BizTalk Editor can be based on any of the following:

  • Well-formed XML

  • XDR-based document templates

  • XDR schemas

  • Document type definitions (DTDs)

  • Microsoft ActiveX® Data Objects (ADO) recordsets stored as XML

  • Electronic data interchange (EDI) (X12 and EDIFACT)

  • Flat files, including delimited and positional files (for example, SAP IDOCs), or flat files that are both delimited and positional

  • Structured document formats

In BizTalk Editor you can open a blank specification, which contains no structure, or you can import an existing schema or specification. For example, you can import a DTD, which is a structured file that denotes elements and attributes as well as any constraints on the order, frequency, and content of the elements and attributes. Standard specifications, such as XML, X12, or EDIFACT, can also be used to create new specifications.

When an instance of a document is imported, BizTalk Editor interprets the structure of the document and produces a specification that is an XDR representation of the document. You can edit any necessary records and fields that appear in the BizTalk Editor specification tree, and then save the structure as a specification. You can import the following file types:

  • XDR schemas

  • Well-formed XML

  • DTDs

Each specification describes the structure of the file, given a specific set of tags. BizTalk Editor also provides several templates that can be used as starting points for creating specifications for common documents, such as purchase orders, invoices, and advance shipping notices.

When BizTalk Server 2002 processes documents, the server uses a map, which you create by using BizTalk Mapper, to translate incoming and outgoing data from one specification format to another.

The following topics are covered in this section:

  • For comprehensive information about BizTalk Editor, see About BizTalk Editor.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Editor Tasks.

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Editor Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk Editor and BizTalk Mapper.


About BizTalk Editor

BizTalk Editor is a graphical tool for defining specifications that are used to initialize the parts of Microsoft BizTalk Server 2002 that read and write data for transactions among organizations and between trading partners. This section provides detailed conceptual information that is essential to understanding BizTalk Editor.

The following topics are covered in this section:

  • Understanding Specifications

  • BizTalk Editor Environment

  • Importing Files

  • Exporting Files

  • Records, Fields, and Properties

  • General Purpose Triggers

  • Namespace Support

  • Adding SQL Annotations

  • Creating XML and Native Instances

  • Validating Instances and Specifications


Understanding Specifications

Specifications are BizTalk Server-specific Extensible Markup Language (XML) schemas that are created by BizTalk Editor. You can create specifications that are based on industry standards (such as XML, EDIFACT, or X12) or non-industry standards (such as delimited flat files, positional flat files, delimited and positional flat files, blank specifications, or existing files).

Industry standards

Industry standards provide uniform ways for businesses to exchange data electronically. The use of a common business language enables computers to communicate within an organization or from one business to another. Industry standards specify the format and data content of electronic business transactions. A specification that is based on an industry standard is considered a subset of the standard. To create a specification that meets your needs, you can begin with an industry-standard specification as a baseline and then delete any records and fields you do not need. In addition, you might need to modify properties for the remaining records and fields.

Electronic data interchange (EDI) is a commonly used industry-standard specification. BizTalk Editor provides a subset of EDI document specifications and an associated EDI code list database. These specifications are generated directly from data obtained from officially recognized publishers of the X12 and EDIFACT standards. It is highly recommended that you validate EDI instances against specifications that are created prior to a production implementation of processes that use these specifications. For more information and updates about EDI specifications and standards, go to the Microsoft BizTalk Server Web site (www.microsoft.com/biztalk/).

Non-industry standards

In specifications that are based on non-industry standards, you must define the structure of the document in BizTalk Editor. You can use BizTalk Editor for various types of non-industry standards: positional flat files, delimited flat files, or combined positional and delimited flat files. To help you better understand how to work with flat files, see the samples included in BizTalk Server 2002. The delimited flat file sample is in the Flat-FileDelimited folder located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\. The positional flat file sample is in the Flat-FilePositional folder located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\.

On the Parse tab, you must set the Structure property of the root node to Delimited if your flat file is both delimited and positional. Additional record properties are set to either Delimited or Positional, depending on their attributes.

For more information about flat files, see Working with Positional and Delimited Flat Files.

Blank specifications

A blank specification contains only the root-node element. If you start from a blank specification, you must build the entire specification structure. Rename the root element and then modify the root-element property values you want to change, such as the heading information for the specification. You can then add records and fields and their properties as required for your business processes.

Existing BizTalk Server 2000 files

Schemas from BizTalk Server 2000 are compatible with BizTalk Server 2002. If you open and save a specification in BizTalk Server 2002 that you created in BizTalk Server 2000, the file format will be changed and you will not be able to open it again using BizTalk Server 2000.

The following topics are covered in this section:

  • Specification Structure

  • Supporting Standards

  • Summary List of Included EDI-Based Documents

  • Working with Positional and Delimited Flat Files

  • Invalid XML Name Characters

  • Invalid Character Ranges

Related Topics

Create a specification based on a flat file

Create a specification based on an empty template

Create a specification based on an existing specification

Create a specification based on a standard

Records, Fields, and Properties

Working with Positional and Delimited Flat Files


Specification Structure

Specifications created by BizTalk Editor are well-formed XML. Specification structures vary depending on the type of file you choose as the basis for building your specification. Regardless of the type, each specification contains the same basic structure. For example, all specifications start with the <?xml version=""?> tag and continue with header information such as the name of the file and namespace data. Then the remaining structure is built based on the records and fields contained within your specification and the attributes associated with the records and fields. You can view the underlying code of a specification by opening it in Microsoft Internet Explorer 5 or later.

BizTalk Editor enables you to create an XML-Data Reduced (XDR) schema with additional BizTalk specific annotations. To remove the annotations, you can use the Export XDR Schema command from the Tools menu. For more information, see Export XDR schemas.

You can create an Extensible (XML) Structure Definitions (XSD) schema from an XDR schema by using the Export XSD Schema command from the Tools menu. For more information, see Export XSD schemas.

Related Topics

Create and Validate Specifications

Export XDR schemas

Export XSD schemas


Supporting Standards

Electronic data interchange (EDI) standards, such as EDIFACT and X12, define a great number of the possible segments and elements that make up the file structure needed in business documents. Using BizTalk Editor, you can start with these structures as the basis for your specification and then remove the segments and elements you do not need. The final structure is a subset of the standard that you and your trading partners, or someone else in your organization, agree to use for business data exchange.

If you create or move nodes in an EDIFACT or X12 document, it is strongly recommended that you set the document standard to CUSTOM. In addition, you should also set the Delimiter Type property to make the altered structure compatible with the rest of the document. Note that if you set the document standard from CUSTOM back to EDIFACT or X12, all Delimiter Type settings will be lost. For more information about setting the CUSTOM property, see Set reference properties. For more information about setting the Delimiter Type property, see Set parse properties.

BizTalk Editor also supports X12 syntax rules, which are relational conditions that exist among two or more data elements for a record. If the specification contains syntax rules, they are enforced during the server run-time process when the specification is validated.

There are five types of rules:

  • All

    If TXI08 exists then the following node must exist:

    • TXI03
  • Grouped

    If either of the following nodes exists, then both must exist:

    • TXI04

    • TXI05
  • Any

    At least one of the following nodes must exist:

    • TXI02

    • TXI03

    • TXI06
  • One

    At most one of the following nodes must exist:

    • TXI02

    • TXI03

    • TXI06
  • Any (conditional)

    If PO413 exists then at least one of the following nodes must exist:

    • PO410

    • PO411

    • PO412

Related Topics

Create and Validate Specifications

Edit Notes and View Syntax Rules

Set reference properties

Summary List of Included EDI-Based Documents


Summary List of Included EDI-Based Documents

BizTalk Editor supports all EDI-based documents. The following table lists the standard specifications, versions, and document standards for EDI-based documents available when you create a new specification based on a standard. For more information, see Create a specification based on a standard.

Standard Version Document standards
X12
  • 2040

  • 3010

  • 3060

  • 4010
  • 810

  • 832

  • 846

  • 850

  • 852 (available in all versions except 2040)

  • 855

  • 856

  • 861

  • 864

  • 867

  • 940 (available only with 3060 and 4010 versions)

  • 944 (available only with 3060 and 4010 versions)

  • 997
EDIFACT
  • D93A

  • D95A

  • D95B

  • D97B

  • D98A

  • D98B
  • APERAK (available in all versions except D93A)

  • CONTRL (available only with D98A and D98B versions)

  • DESADV

  • INVOIC

  • INVRPT

  • ORDERS

  • ORDRSP

  • PARTIN

  • PAYEXT

  • PRICAT

  • PRODAT (available only with D97B, D98A, and D98B versions)

  • RECADV (available only with D97B, D98A, and D98B versions)

  • SLSRPT
XML
  • N/A
  • BTF1 Envelope

  • CanonicalReceipt

  • CommonAdvancedShipNotice

  • CommonInventoryAdvice

  • CommonInvoice

  • CommonPartnerProfile

  • CommonPO

  • CommonPOAcknowledgment

  • CommonPriceCatalog

  • CommonShippingAdvice

  • CommonShippingOrder

  • Simple SOAP Envelope

Related Topic

Create a specification based on a standard


Working with Positional and Delimited Flat Files

BizTalk Editor is designed to make it easy to create specifications with positional flat files, delimited flat files, and combined positional and delimited file structure. The following sections provide specific details about each of these file structures.

Positional flat files

A positional flat file is made up of fields that are the same fixed length and records that have a common end-of-record terminator. The structure of an incoming file must be represented in the records and fields of the source specification so the positional nature of the incoming file is preserved. Therefore, before defining the document structure of a source specification, obtain a layout of the necessary records and fields.

The following table shows an example of a fixed format.

Name | Address | City | Phone
Xxxxxxxxxx | Aaaaaaaaaa | Ccccccccccccccc | xxx-xxx-xxxx
Yyyyyyyyyy | Bbbbbbbbbb | Ddddddddddddd | xxx-xxx-xxxx

The Name field is fixed at a maximum of 10 characters, the Address field maximum is 10 characters, the City field maximum is 15 characters, and the Phone field maximum is 12 characters. The end-of-record terminator is a carriage return and/or line feed character or characters.

You can use BizTalk Editor to create consecutive records and fields. You can create multiple record types and assign different delimiters for parent records. For structures that contain multiple record types, the specification of the types and record terminators must also be specified in the order in which they appear in the document. Fields must be specified by start position, length, and data type.

If a specification is positional and you change the structure to delimited, the compiled specification includes the original start position and end position specified on the Reference tab. However, when BizTalk Server 2002 parses a specification, the parser ignores this information and processes the specification as a delimited file.

A positional record must always be a child of a delimited record. The delimiter character specified for the parent-delimited record must not appear in the data of the child positional record. There is no way to escape the delimiter character of the parent-delimited record in the data of the child positional field. For more information about delimiters and escape characters, see Set parse properties.

To help you better understand how to work with positional flat files, see the sample in the Flat-FilePositional folder located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\.

Note

  • On the Parse tab, you must set the Structure property of the root node to Delimited if your flat file is both delimited and positional. Additional record properties are set to either Delimited or Positional, depending on their attributes.

Delimited flat files

A delimited flat file contains one or more records separated by a delimiter. BizTalk Editor does not read delimiters as part of the data. However, if the delimiter character does appear as data, the data can be formatted so the data and the delimiter are distinguishable. For example, the field in which a delimiter character appears can be enclosed in quotation marks to indicate that the delimiter character is to be treated as data and not as a delimiter.

Using BizTalk Editor, you can select specific fields and the delimiters that are associated with them. You can also specify end-of-record delimiters. To enable the use of delimited flat files, BizTalk Editor supports:

  • Structures that consist of multiple groups of records.

  • Multiple record types that are defined by record-type tags.

  • End-of-record delimiters.

  • Wrap and escape characters, to distinguish between field data and delimiter values.

  • Field start, length, and type values.

  • Field content tags and descriptions.

  • The ability to transform flat files into specifications that can be used by BizTalk Mapper.

To help you better understand how to work with delimited flat files, see the sample in the Flat-FileDelimited folder located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\.

Note

  • On the Parse tab, you must set the Structure property of the root node to Delimited if your flat file is both delimited and positional. Additional record properties are set to either Delimited or Positional, depending on their attributes.

Related Topic

Create a specification based on a flat file


Invalid XML Name Characters

Unicode characters that range from xF900 to xFFFE are not valid in Extensible Markup Language (XML) names. If you use an invalid Unicode character in an XML name, that character is translated into an escaped numeric entity when you view it in the specification tree. The escaped numeric entity is encoded as _xHHHH_, where HHHH stands for the four-digit hexadecimal Unicode code. For example, the name Ship To in a purchase order specification contains a space character, and appears in a specification tree as Ship_x0020_To. If you move the mouse pointer over a node that contains an encoded Unicode character, a ToolTip appears that displays the node name with the unencoded Unicode character. This occurs when you view a specification tree in BizTalk Editor or in BizTalk Mapper.

Related Topics

Create and Validate Specifications

Validate a document instance


Invalid Character Ranges

You can block a character or a range of characters from being output by BizTalk Server 2002. To do this, in BizTalk Editor, open a specification that is to be used as a destination specification. Open the Invalid Character Ranges dialog box and enter the characters or the character ranges that you want to prevent being output by BizTalk Server. Whenever BizTalk Server attempts to process a character specified in the Invalid Character Ranges dialog box of an output specification, processing stops and an error message appears.

Note

  • Character ranges can be blocked only for non-Extensible Markup Language (XML) documents.

Related Topics

Add invalid character ranges

Delete invalid character ranges

Edit invalid character ranges

Using BizTalk Mapper


BizTalk Editor Environment

When you open BizTalk Editor, you will see a graphical user interface that enables you to create and work with specifications easy.

The following topics are covered in this section:

  • BizTalk Editor User Interface

  • BizTalk Editor Menus

  • BizTalk Editor Toolbar Buttons


BizTalk Editor User Interface

The BizTalk Editor user interface has three main panes. The left pane displays the specification tree, which is a graphical representation of a specification. The top node in the specification tree is the root node; it is represented by a book icon Root node. Records and fields are displayed below the root node in the specification hierarchy. Records are represented by a document icon with green horizontal lines Record node. Fields are represented by a document icon with vertical blue lines Field node. For more information about records and fields, see Records, Fields, and Properties. You can expand or collapse a node in the specification tree by clicking the expand indicator (+) or collapse indicator (-) to the left of the node.

The right pane contains six tabs: Declaration, Reference, Parse, Namespace, Dictionary, and Code List. Use these tabs to set property values, namespaces, dictionary properties, and code lists for nodes in a specification. For more information about these tabs, see Specify Properties for Records and Fields.

The bottom pane contains two tabs: Output and Warning. The Output tab displays an Extensible Markup Language (XML) document instance created when using the Create XML Instance command or a flat file when using the Create Native Instance command in BizTalk Editor. For more information about creating an XML document instance from a specification, see Create a document instance or Create a native instance. The Warning tab indicates whether an attempt to validate a document instance against a specification was successful, and displays warnings related to an unsuccessful document validation attempt. For more information, see Validate a document instance.

Related Topics

Create a document instance

Create a native instance

Specify Properties for Records and Fields

Validate a document instance


BizTalk Editor Menus

BizTalk Editor menus logically group commands together, making it easy to perform a specific task. For example, you can use the commands on the View menu to view or to collapse all the records and fields in the specification tree.

The BizTalk Editor menus are as follows:

  • File. Use this menu to create, open, save, or close a specification.

  • Edit. Use this menu to cut, copy, paste, insert, rename, or delete records or fields in a specification.

  • View. Use this menu to:
    • Select views in the right pane of the user interface.

    • Select views in the bottom pane of the user interface.

    • Select a text size for the BizTalk Editor display.

    • Display the Invalid Character Ranges dialog box.

    • Expand or collapse the specification tree.

    • Highlight the next warning on the Warnings tab.
  • Tools. Use this menu to:
    • Validate a specification.

    • Validate a document instance against a specification.

    • Create an Extensible Markup Language (XML) document instance or native instance from a specification.

    • Import files.

    • Export XML-Data Reduced (XDR) schemas or XSD schemas.

    • View BizTalk Editor options.
  • Help. Use this menu to get conceptual information, understand why tasks are important, and view procedural content about using BizTalk Editor.

Related Topic

BizTalk Mapper Menus


BizTalk Editor Toolbar Buttons

BizTalk Editor provides a toolbar to complement the menu bar. All of the toolbar buttons display graphic representations of the tasks they perform. They appear in the following order from left to right:

  • New

  • Open

  • Save

  • Retrieve from WebDAV

  • Store to WebDAV

  • Cut Specification Node

  • Copy Specification Node

  • Paste Specification Node

  • Delete Specification Node

  • New Record

  • New Field

  • Insert Record

  • Insert Field

  • Collapse

  • Expand


Importing Files

BizTalk Editor enables you to import files. It creates the file structure; however, you must assign all record and field property values. The following types of files can be imported into BizTalk Editor:

  • Well-formed XML instances

  • Document type definitions (DTDs)

  • XML-Data Reduced (XDR) schemas

  • Microsoft Office files (using the well-formed XML import module)

However, you cannot import a file if it contains an external reference to another file. After importing a well-formed XML instance, a DTD, an XDR schema, or a Microsoft Office file, BizTalk Editor creates a structure that is based on the imported file and displays a set of records and fields. However, if the file that you import has an element that has content, is repeated in the instance data, and has no children, BizTalk Editor creates it as a field, rather than a record, when it imports the structure. After you save the file in BizTalk Editor, the file becomes a specification. This specification has the appropriate header information, and it adheres to a specified structure.

BizTalk Editor is able to determine which element should be the root node. However, in some cases if it is unable to determine the appropriate root node element, a dialog box displays that prompts you to specify the element that is the root node. However, if the <schema> node has a name="a_name" attribute on it, BizTalk Editor uses this element name as the root node and will not prompt you to select a root node even if there are multiple candidates or the root indicated by name is involved in a cycle. If you want to be able to select a root node, you must open the XDR file and remove the name="a_name" attribute. Then import the file and BizTalk Editor will prompt you to select a root element.

The following topics are covered in this section:

  • Importing Well-formed XML

  • Importing DTDs

  • Importing XDR Schemas

  • Importing Microsoft OfficeXP Files

Related Topic

Create a specification based on an imported file


Importing Well-formed XML

Well-formed Extensible Markup Language (XML) includes any Microsoft Office files you might import. If you have a well-formed XML instance that contains an XDR schema, you cannot import it. And, when importing well-formed XML, BizTalk Editor cannot interpret data type or field length parameters. BizTalk Editor might displays warnings related to cyclical references after importing a well-formed XML file. If this occurs, it is highly recommended that you fix the warnings and save the specification before continuing.

If you import a well-formed XML file that contains a namespace on the root node, the namespace becomes the target namespace and is ignored elsewhere in the specification. For more information about target namespaces, see Set reference properties.

Related Topic

Create a specification based on an imported file


Importing DTDs

When importing document type definitions (DTDs), BizTalk Editor cannot interpret data type or field length parameters. There are some specific cases where data types are treated uniquely. The following table lists some of these cases.

When these data types exist | The DTD file
entity and entities | Can be imported, but the data types are removed.
nmtoken and nmtokens | Can be imported, but the data types are removed.
notation | Can be imported, but the data type is imported as an enumeration type.

If the last line of a DTD is an entity reference (for example, "%xx"), the DTD cannot be imported into BizTalk Editor. However, if you create a new line at the end of the DTD that contains an end-of-line character, BizTalk Editor will import the DTD.

When a DTD has multiple roots, BizTalk Editor will not necessarily issue a warning on every replacement during import.

In addition, you cannot import a DTD if it contains comments within elements. To import these DTDs successfully, you must edit the affected files to remove any comments within elements.

Related Topic

Create a specification based on an imported file


Importing XDR Schemas

When importing XML-Data Reduced (XDR) schemas, there are some data types that BizTalk Editor will handle uniquely. The following table lists some of these data types.

When these data types exist | The XDR schema file
entity and entities | Cannot be imported.
nmtoken and nmtokens | Can be imported, but the data types are removed.
notation | Cannot be imported.

You cannot import an XDR schema if the default value for an attribute of type IDREFS is specified in the attribute declaration. For example:

<AttributeType name="Field1" d:type="idrefs" default="a1 a2"> </AttributeType>
<attribute type="Field1" required="no"></attribute>

The solution to this issue is to move the default value to the attribute reference in the XDR schema before importing it into BizTalk Editor, as shown in the following code:

<AttributeType name="Field1" d:type="idrefs"> </AttributeType>
<attribute type="Field1" required="no" default="a1 a2"></attribute>

Related Topic

Create a specification based on an imported file


Importing Microsoft Office XP Files

BizTalk Editor removes the ss Microsoft Office XP namespace, but does not remove other custom namespaces. However, prefixes of custom namespaces will be replaced. For example, 0:abc will become 0_abc. If a Microsoft Excel spreadsheet (saved as an XML file) contains the following information:

<Workbook xmlns="urn:schemas-microsoft-com:office:spreadsheet"
 xmlns:o="urn:schemas-microsoft-com:office:office"
 xmlns:x="urn:schemas-microsoft-com:office:excel"
 xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet"
 xmlns:html="http://www.w3.org/TR/REC-html40">

BizTalk Editor recognizes that the target namespace xmlns is the same as the prefixed namespace xmlns:ss. Therefore, rather than use the ss prefix redundantly throughout the schema, BizTalk Editor dropped the ss prefix wherever it is used because it is the same exact namespace being defined as the target namespace.

Related Topic

Create a specification based on an imported file


Exporting Files

You can export new and existing specifications only while they are open in BizTalk Editor. When you export a specification, BizTalk-specific annotations are removed from the structure, and the resulting structure is saved as a general schema that can be used by other applications. You can export both XML-Data Reduced (XDR) schemas and Extensible (XML) Structure Definitions (XSD) schemas.

In addition, you can create an XSD schema from an XDR schema with a conversion script provided with a complete installation of BizTalk Server 2002.

Related Topics

Export XDR schemas

Export XSD schemas


Records, Fields, and Properties

BizTalk Editor presents a specification as a tree view of records and fields in a given order. Within this structure, you can create parent-to-child relationships by using records and fields. Records can contain other records or fields, but fields cannot contain other fields or records. A record is always an element, but a field can be either an element or an attribute.

You can add and insert records and fields to records and you can insert records and fields to fields. You cannot add records or fields to a field. The following illustration explains how records and fields are placed in relationship to a particular node in the tree.

Illustration of record and field organization

Selecting BlankSpecification and clicking the Add Record button will create Record1 and clicking the Add Field button will create Field1. This is represented as section A in the illustration. Selecting Record1 and clicking the Add Record button will create Record2 and clicking the Add Field button will create Field1 (the one located below Record2). This is represented as section B in the illustration. Selecting Record1 and clicking the Insert Record button will create Record3 and clicking the Insert Field button will create Field2. This is represented as section C in the illustration.

The specification tree, which presents the records and fields as nodes, provides you with an easy way to view, create, edit, and delete all the records and fields in a specification. Each node in the specification tree has a set of property definitions, which are represented on six tabs in the main window of BizTalk Editor: Declaration, Reference, Parse, Namespace, Dictionary, and Code List. The data on these tabs is necessary for BizTalk Editor to translate a document from its original format to Extensible Markup Language (XML). The information defines the structure of the document, whether the document is positional or delimited, the order and length of the data, and the format of the data.

The following topics are covered in this section:

  • Records and Their Properties

  • Supported Time Format for X12

  • Mixed Content Support

  • Fields and Their Properties

  • Calculating Field Positions

  • Character Length Limits

  • Code List Values and Descriptions

  • Pad Characters

  • Property Scope

  • Cyclical References

  • Default Value Integration

  • Summary of Data Types and Data Type Values


Records and Their Properties

Depending on the type of specification you are building, you might need to add and/or remove records. After adding records to any specification, you must specify properties. If you remove a record, its properties are also removed, along with all child records and fields.

If your specification is based on X12 or EDIFACT, you can add only the type of records that exist in that standard, but you can remove any or all records. If you are building a specification that is based on a blank specification, you must add records. In some cases, such as when you are building a new specification that is based on an existing specification, you might need to add and remove records.

When you add or insert a record, you can immediately begin typing to rename the record. You can edit the name of an existing record and its properties by selecting the record and editing as appropriate.

If you paste into a specification a record with a name that is the same as an existing record, a number is appended to the end of the name of the record you are pasting.

For information about creating a new instance of an existing record, see Create a new instance of an existing record. For information about creating a cyclical reference, see Create cyclical references.

Related Topics

Create a new instance of an existing record

Create cyclical references

Property Scope

Specify Properties for Records and Fields


Supported Time Format for X12

In BizTalk Editor, the supported time format for the X12 syntax (indicated when standard=X12 on the Reference tab for the root node of the schema) is HHMMSSDD, where:

  • HH represents hours. Valid input is 00 through 23.

  • MM represents minutes. Valid input is 00 through 59.

  • SS represents integer seconds. Valid input is 00 through 59.

  • DD represents decimal seconds. Decimal seconds can be sent in one the following formats:
    • D represents tenths of a second. Valid input is 0 through 9.

    • DD represents hundredths of a second. Valid input is 00 through 99.

      If you want to express time up to the tenths or hundredths of a second, use the Custom Date/Time Format data type described in the Apply the Custom Date/Time format property.

    Using this format, data that satisfies the input range restrictions listed previously can be four, six, seven, or eight digits in length. In other words, specifying HHMMSSDD for a time format means that instance data must match HHMM, HHMMSS, HHMMSSD, or HHMMSSDD.

  • All time fields using the HHMMSSDD custom format will be treated as strings because XML does not support decimal seconds or hundredths of seconds. The Create Native Instance feature will not create HHMMSSDD custom format.


Mixed Content Support

BizTalk Editor supports mixed content primarily for organizations that use XDR schemas natively. If a schema has mixed content, it means that an element contains both textual and sub-element content. You can specify that the content of the schema is mixed by selecting Mixed as the Content value on the Declaration tab. This attribute applies only to Extensible Markup Language (XML) document types and can be specified only to the record level of a schema, not the field level.

The following example illustrates a schema fragment for content that has the "mixed" property value:

<ElementType name="ProgramManager" content="mixed">
<element  type="Name" >
<element type="OfficeNumber" >
</ElementType>

The following example illustrates a schema fragment representing an XML instance:

<ProgramManager>
A program manager named <Name>Mike Hines</Name> works in office <OfficeNumber>2234</OfficeNumber>.
</ProgramManager>

In the previous example, if the contents of the <Program Manager> element was linked from a Source Specification tree in BizTalk Mapper to a record in the Destination Specification tree, the resulting output would be as follows:

A program manager named Mike Hines works in office 2234.

Related Topic

Set declaration properties


Fields and Their Properties

Depending on the type of specification you are building, you might need to add and/or remove records. Fields correspond to electronic data interchange (EDI) elements. After adding fields to any specification, including EDI documents, you must specify property values.

If your specification is based on X12 or EDIFACT, you can add only the type of fields that exist in that standard, but you can remove any or all fields. If you are building a specification that is based on a blank specification, you must add fields. Regardless of the document type, you can change the properties of any field.

When you add or insert a new field in a specification, the Type property, located on the Declaration tab, is set to Attribute by default. You can manually change this value to Element for any field. For information about creating new fields with the Type property set to Element by default, see Create a new field as an element.

When you add or insert a field, you can immediately begin typing to rename the field. You can edit the name of an existing field and its properties by selecting the field and editing as appropriate.

If you paste into a specification an element field with a name that is the same as an existing element field, a number is appended to the end of the name of the field you are pasting. If you paste into a specification a field with the same name as an existing sibling field (and both fields have the same Type value), a number is appended to the end of the name of the field you are pasting. For more information about Type values, see Set declaration properties. For information about creating a new instance of an existing element field, see Create a new instance of an existing element field

Related Topics

Create a new field as an element

Create a new instance of an existing element field

Property Scope

Set declaration properties

Specify Properties for Records and Fields


Calculating Field Positions

BizTalk Editor can automatically calculate the start and end positions for all the fields in a positional record. First set a Data Type value and a Maximum Length value in the Declaration tab for each field in the positional record. Then right-click the positional record and, on the shortcut menu, click Calculate Field Positions. The start and end positions for the fields in that record are automatically calculated. For more information, see Automatically calculate field positions.

The field positions of a record are calculated from the first field in the record sequentially to the last field. When calculating field positions, if a field is encountered that does not have a value set for the Maximum Length property, the start and end positions for that field and all subsequent fields of the record are not calculated. The start and end positions of a field with a Maximum Length value of 1 are equal. If a sibling record is encountered when calculating field positions, the start and end positions for all fields after the sibling record are not calculated.

If there are start and end positions specified for the fields in a positional record, all but the start position of the first field are overwritten when you calculate field positions. When you calculate field positions, the Start Position of the first field of a positional record is set to 1, unless a Start Position value was set previously for that field. If a Start Position value has already been set for the first field of a positional record, calculations begin from that value. In addition, when calculating field positions for a positional record, the positions of fields contained by all descendent records are also calculated. The positions of sibling fields that occur before a record are calculated, but positions of sibling fields that occur after a record are not calculated.

Field position calculation takes the Source Tag Identifier into account when calculating field positions. For example, consider a positional record with the following properties:

  • The Source Tag Identifier is "TAG".

  • The Source Tag Position is 10.

  • There are four fields with Maximum Length values of 2, 5, 8, and 6.

  • There is no Start Position value set for the first field.

The start and end positions for the four fields are:

  • Field 1 = 1, 2

  • Field 2 = 3, 7

  • Unused = 8, 9

  • TAG = 10, 12

  • Field 3 = 13, 20

  • Field 4 = 21, 26

If the Source Tag Position had been 1, "TAG" would have had start and end position values of 1 and 3, and the field count would have started at position 4.

Related Topic

Automatically calculate field positions


Character Length Limits

There are limits to the number of characters that you can use in names and property values. The following table shows the character limits in BizTalk Editor.

Name or property value | Maximum number of characters
Node name (the name of a root node, a record, or a field) | 255
Namespace prefix | 64
String property value | 1024
LONG property value | 11
ULONG property value | 10
CHAR property value | 1
Electronic data interchange (EDI) format property value (the value of an EDI-specific format property, such as the Custom Date/Time Format property value on the Parse tab for a field in an EDI-based specification) | 15
Target Namespace | 255
Specification name | 255

Related Topics

Set declaration properties

Set reference properties

Set parse properties

Declare namespaces

Set dictionary properties


Code List Values and Descriptions

The information contained on the Code List tab specifies X12 or EDIFACT code values and their descriptions. Only specifications that are based on an X12 or EDIFACT standard have code lists. The descriptions define the meaning of each code. For example, the code value ST in the Address Qualifier Code field of many standard document specifications means that the information given is for a Ship To address. The codes in the list cannot be modified or deleted. You can only choose whether or not to associate a code with a field.

Not all fields in a specification that is based on X12 or EDIFACT have codes associated with them. A complete list of available codes for a specific field appears on the Code List tab if that field has a code list reference. Codes are valid for a field if the check box in the Value column next to the code is selected. A description of the code appears in the Description column. If you associate a code with a field, the Type value on the Declaration tab must be set to Attribute.

You can include or exclude codes associated with a field by selecting or clearing the check boxes in the Value column next to the code listed on the Code List tab. Codes are listed by numeric value or alphabetic value, or by a combination of numeric and alphabetic values. The value represents a specific description. You can associate a code value to any field in the specification tree. For example, in the BEG02 field of an X12 850 purchase order, you can select the code OS, which adds an attribute to the BEG02 field that indicates that the field contains special order information.

Custom structure affects code lists

If you change the structure of an X12-based or EDIFACT-based specification to CUSTOM, and then change it back again to X12 or EDIFACT, the code list for a particular field might no longer be available on the Code List tab. If this happens, save the specification and then reopen it. The code list will reappear on the Code List tab for the appropriate field.

Code list database location

Code list values and descriptions for the EDI-based specification templates that are provided by BizTalk Server 2002 can be found in the Microsoft Access database file at \Program Files\Microsoft BizTalk Server\XML Tools\Databases\CodeLists\CodeListsX12a.mdb. If you create new tables in this database for new specification templates, the format for the table name is standard_version. For example, for a D99A EDIFACT specification template, the corresponding table name would be EDIFACT_D99A.

Important

  • If you create a new table in the CodeListsX12a.mdb database, do not put invalid Extensible Markup Language (XML) characters (Unicode characters from F900 to FFFE) into the Value column of the table. If you save a specification that contains a field with a selected code list value that is associated with a value in a table with an invalid XML character, you will be unable to open the specification.

Related Topics

Clear codes

Select codes

Specify Properties for Records and Fields


Pad Characters

BizTalk Editor enables you to manage pad characters in delimited documents to ensure that you get the output that you expect. Because every delimited document that is processed by BizTalk Server 2002 must be translated into Extensible Markup Language (XML) before mapping takes place, you must make sure that your document specification tells BizTalk Server how to handle pad characters in delimited document instances. For example, you might have a field in a delimited document instance that looks like this:

Green*****

The data content of the field is Green, the field is left justified, there are five pad characters to the right of the data content, and the pad character is an asterisk (*).

If you do not define the pad character for the field in the specification that corresponds to the field in the document instance, BizTalk Server interprets the five asterisks to be part of the data content of the field. To ensure that BizTalk Server correctly handles the pad characters in this field, you need to make sure the properties on the Parse tab for this field are set as in the following table.

Property | Value
Justification | Left
Pad Character | *
Minimum Length with Pad Character | Set this property value if you want the length of the field in your output instance to be greater than or equal to a certain length. BizTalk Server inserts pad characters into the field to achieve the correct minimum field length in the output instance.

You can use the Pad Character property to ensure that pad characters in a field are removed from a document instance submitted to BizTalk Server. The Minimum Length with Pad Character property value ensures that BizTalk Server inserts pad characters into a field in the output instance, if this is wanted. The Justification property indicates on which side of the field data content the pad characters are removed (from the input document instance) or inserted (into the output instance). Trailing pad characters are added to or removed from a field that is left justified, and leading pad characters are added to or removed from a field that is right justified. If the Pad Character property for a field is not set, no pad characters are added to or removed from that field.

Related Topic

Set parse properties


Property Scope

If you have two or more instances of a record in a specification, the values of certain properties for these instances must be identical. In other words, the scope of these properties is global. The scope of certain field properties can also be global, but only if the Type property for the field is set to Element. Whereas, the scope of a field with the Type property set to Attribute is always local.

For example, all the properties on the Declaration and Parse tabs are identical for multiple instances of a record or a field. If you change a declaration or parse property for one instance of a record or a field, that property automatically changes for all other instances of that record or field. The properties on the Reference and Dictionary tabs are not global in scope, however, so the values for these properties can be set independently for each instance of a record or a field. Code lists apply only to fields, and they are not global in scope.

Note

  • In BizTalk Editor, only ElementType declarations are global in scope. If you import a schema into BizTalk Editor that contains AttributeType declarations that are global in scope, and then save the schema as a specification, the AttributeType declarations are automatically made local in scope within the appropriate ElementType declaration or declarations.

Related Topics

Set declaration properties

Set parse properties


Cyclical References

A cyclical reference in a specification occurs when a record is created as a descendant to itself. A cyclical reference can occur only when the Standard property value is set to XML on the Reference tab. BizTalk Editor represents a cyclical reference with an icon Cyclical reference icon that appears as a record with a curved arrow through it.

The following illustration shows how a cyclical reference appears in BizTalk Editor.

The Cycle Count property appears on the Declaration tab and applies only to a cyclical node. The default value is 7. The cycle count indicates how many cycles are available below the base record. For example, in the previous illustration there are a total of four levels for Record1: three from the cycle count of 3 and one from the base record. If you open this specification in BizTalk Mapper, all four levels of Record1 appear. A Field1 and Record2 also appear for every Record1. You can connect links to nodes on any level of the cycle.

It is not possible to set dictionary property values for fields that descend from a cyclical node. For example, in the previous illustration, you can set dictionary property values for Root/Record1/Field1, but you cannot set dictionary property values for any of the three Field1 references that cycle below Root/Record1/Record1.

Cyclical references are subject to the following restrictions:

  • Nodes on a cycle path (the nodes that occur between the first record and the last record in a cyclical reference) cannot appear anywhere else in the specification.

  • Elements on a cycle path cannot be the source or target of any drag-and-drop or cut-and-paste operation.

  • Cycles cannot overlap.

  • The base record of a cyclical reference cannot be the root node of the specification.

Important

  • The Minimum Occurrences property on the Reference tab for the cyclical reference node must be set to 0. Setting it to 1 causes an infinite loop.

  • If you import a schema that contains a cyclical reference, BizTalk Editor does not automatically check to ensure that the cyclical reference is valid.

Related Topics

Create cyclical references

Property Scope


Default Value Integration

If a source specification contains a field of type Attribute, and an incoming document instance that is based on the source specification does not include that field, you might want the specification to provide a default value for the field.

If an incoming document instance does not contain the field, the default value for the field is provided. If an incoming document instance contains the field, the default value is ignored.

Related Topic

Set declaration properties


Summary of Data Types and Data Type Values

The following list provides details and examples to help you specify a value for the Data Type property on the Declaration tab. After you select one of the following options from the Data Type list, you might need to specify a value in the Data Type Values box.

Data type

Character

Contains a string, one character long.

String

Contains any text.

Number

Contains a number of digits and can have a leading sign, fractional digits, and an exponent. This follows standard English-language punctuation; for example, 15, 3.14, -123.456E+10.

Integer (int)

Contains a number and can include an optional sign. It cannot contain a fraction or exponent; for example, 1, 58502, -13.

Float

Contains a number, with no limit on digits; it can potentially have a leading sign, fractional digits, or an exponent.

Fixed Point (14.4)

The same as Number, but can contain no more than 14 digits to the left of the decimal point and no more than 4 to the right; for example, 12.0044. This data type can be used for currency values.

Boolean

Contains an expression that is evaluated as either TRUE (1) or FALSE (0).

Date

Contains a date in a subset ISO 8601 format, with no time information; for example, 1988-04-07.

Date Time

Contains a date in a subset ISO 8601 format, with optional time and no optional zone information. Fractional seconds can be as precise as nanoseconds; for example, 1988-04-07T18:39:09.

Date Time.tz

Contains a date in a subset ISO 8601 format, with optional time and optional zone information. Fractional seconds can be as precise as nanoseconds; for example, 1988-04-07T18:39:09-08:00.

Time

Contains a time in a subset ISO 8601 format, with no date and no time zone information; for example, 08:15:27.

Time.tz

Contains a time in a subset ISO 8601 format, with no date information but with optional time zone information; for example, 08:15:27-05:00.

Byte (i1)

Contains a number and can contain an optional sign, such as a minus (-) sign. It cannot contain a fraction or an exponent; for example, 1, 127, -128.

Word (i2)

Contains a number and can contain an optional sign, such as a minus (-) sign. It cannot contain a fraction or an exponent; for example, 1, 703, -32768.

Integer (i4)

Contains a number and can contain an optional sign, such as a minus (-) sign. It cannot contain a fraction or an exponent; for example, 1, 703, -32768, 148343, -1000000000.

Double Integer (i8)

Contains a number and can contain an optional sign, such as a minus (-) sign. It cannot contain a fraction or an exponent; for example, 1, 703, -32768, 148343, -1000000000.

Unsigned Byte (ui1)

Contains a number. It cannot contain a sign, fraction, or exponent; for example, 1, 255.

Unsigned Word (ui2)

Contains a number. It cannot contain a sign, fraction, or exponent; for example, 1, 255, 65535.

Unsigned Integer (ui4)

Contains a number. It cannot contain a sign, fraction, or exponent; for example, 1, 703, 3000000000.

Double Unsigned Integer (ui8)

Contains a number. It cannot contain a sign, fraction, or exponent; for example, 1, 703, 3000000000.

Real (r4)

Contains a number that has a minimum value of 1.17549435E-38F and a maximum value of 3.40282347E+38F; for example, 3.14285718E+2.

Double Real (r8)

Contains a number that has a minimum value of 2.2250738585072014E308 and a maximum value of 1.7976931348623157E+308, for example, .314159265358979E+1.

Universal Unique Identifier (uuid)

Contains hexadecimal digits representing octets, with optional embedded hyphens that can be ignored; for example, 333C7BC4-460F-11D0-BC04-0080C7055A83.

Uniform Resource Identifier (uri)

Contains a Uniform Resource Identifier (URI).

Binary (base64)

Contains binary encoding of binary text into characters; for example, conversion of a Graphic Interchange Format (GIF) image into a text representation.

Binary (hex)

Contains a binary hexadecimal digit that represents octets; for example, 0x0ffaa.

ID

Specifies the field as the ID.

IDREF

Specifies that the field be referenced to the field containing the ID value.

IDREFS

Specifies that the field hold a list of IDs, each separated by a space.

Enumeration

Assigns an ordinal sequence to a series of values; for example, Monday, Tuesday, Wednesday might be enumerated as 1 2 3.

Note

  • The Fixed Point (14.4) data type can be used for currency values.

  • If you want to use a filter for a date/time type (dateTime, dateTime.tz, time, time.tz) you must enter it manually in the XPath expression. For example, self::node()[@ATTDATETIME = "2000-03-15T10:10:10"] where ATTDATETIME is the date/time format type.

Related Topic

Set declaration properties


General Purpose Triggers

BizTalk Editor provides a property called Trigger Field on the Parse tab to identify a trigger field for any segment type for Microsoft® BizTalk™ Accelerator for HIPAA schemas. A trigger field is basically a form of content-qualified tagging. The existing Enumeration data type and Values attribute specify the value(s) that causes the trigger to be identified. The parser interprets this trigger field during parsing and matches instance content with the node in the schema that has the corresponding trigger value(s).

There are 11 segment types that use trigger fields to further define their meaning. The following table lists these segment types and the corresponding trigger fields.

Segment | Trigger field
AMT | AMT01
CRC | CRC01
DTM | DTM01
DTP | DTP01
ENT | ENT02
HI | HI01:01 (01 is a composite, first subfield)
N1 | N101
NM1 | NM01
NTE | NTE01
REF | REF01
RMR | RMR01

BizTalk Editor enables duplicate peers to exist if all of them use trigger fields with values that are mutually exclusive. In other words, duplicate peers continue to be prohibited when they introduce ambiguity.

Triggers easily extend to loop interpretation as well, because the trigger segment (that is, the segment housing the trigger field) is always the first segment in the loop. Triggers are also supported on segments that may be nested inside of a loop.

BizTalk Editor is not able to validate that enumerations do not overlap on the trigger value on the same source tag identifier. If you edit the properties and create an overlap, a run-time error will occur. Annotations you add that are needed to support segment nesting are not lost when saving a specification.

In addition to the segment types mentioned in the previous table, there is also a special case Hierarchical Level (HL) segment. For more information about this segment, see HL Segment Special Case.

Important

  • Trigger fields can be attributes only of the record or loop being triggered. This is because all fields in X12 schemas are represented using attributes.

The following topics are covered in this section:

  • Trigger Field Validation

  • HL Segment Special Case

  • Instance Structure Limitations

  • HL Validation

Related Topic

Set parse properties


Trigger Field Validation

At design time, BizTalk Editor validates only that the specified trigger field exists and that it is an attribute. Beyond that, all remaining validations occur at run time. All of the supplied HIPAA schemas validate at run time. Their validation criteria are:

  • Peer element nodes with the same source tag identifier must have the same structure and must specify the same trigger field in their respective hierarchies.

  • Each peer element node defines mutually exclusive enumeration values for the common trigger field.

  • Instance data that does not match any of the possible structures' trigger values is flagged as unexpected data found in the instance—the same behavior as if the source tag identifier could not be found in the schema.

  • If there are nested triggers in the schema and the first child record of the triggered loop is also triggered, then that child record cannot repeat.

  • Similarly, for all peer triggered segments, in terms of their minimum/maximum occurrence settings, the 1/1s come first, followed by the 1/*, followed by the 0/[1|*]. Failure to meet this requirement results in a parsing error.

Related Topic

Set parse properties


HL Segment Special Case

Using Hierarchical Level (HL) segments is a special case for trigger fields because in addition to interpreting the trigger field values, it also requires keeping track of parent-child relationships. The HL segment contains the following fields, in order:

  1. Numerical sequence ID from top to bottom of the document, starting at "1"

  2. Parent sequence ID

  3. Level indicator of the trigger field (for example, 22=Subscriber, 23=Dependent)

  4. Child indicator (0=No; 1=Yes)

The parser uses the contents of these fields to construct a hierarchy for the HL segments encountered. While this hierarchy does not explicitly contradict the schema, the contents of the HL segment cause the parser to interpret the structure differently.

There are also serializer implications for HL segments. You should not have to build contents for fields 1 and 2 (listed previously) in the BizTalk Server 2002 mapping process. If you do build contents for these fields, the serializer will overwrite them.

Related Topic

Set parse properties


Instance Structure Limitations

The X12 parser imposes two restrictions on instance structure permutation with respect to Hierarchical Level (HL) segments:

  • No skips. This is a schema restriction whereby any HL segment/loop must be exactly one level deeper from the root than its parent HL segment/loop, if it has a parent HL. For example, HL1/N1/HL2 is not supported. In other words, a sequence of "x" nested HLs must span exactly "x" generations of depth in the tree. The following illustrations show examples of HL segment/loop scenarios that are allowed and not allowed.

    Examples of allowed and not allowed HL segment/loop scenarios

  • No jumps. This data limitation prevents you from specifying an out-of-order hierarchy. For any HL that makes reference to a parent HL, there cannot be any other HLs between them in sequence in the instance data stream. This is referred to as "no jumps" because, drawn as a family tree, the proscribed action amounts to jumping from one branch to another, and then back in the HL encounter sequence. The following table illustrates this "no jumps" limitation.
    ID | Parent
    1 -
    2 | 1
    3 | 2
    4 | 3
    5 | 1
    6 | 4

    Moving down the HLs sequentially, as they are encountered in the parser data stream, each is a child of the previous one, until #5, which is a repeat occurrence of #2. This is allowed and expected. It is then followed by #6, which attempts to identify itself as a child of #4. This is not allowed because sequentially #5 sits between #6 and the HL it calls its parent (#4).

Note

  • Modifying the HIPAA-specific schemas supplied with Microsoft BizTalk Accelerator for HIPAA is possible with BizTalk Editor. You should use caution when changing the schemas to ensure that you remain in compliance with various aspects of the HIPAA implementation guides.

Related Topic

Set parse properties


HL Validation

In addition to the trigger field validations described in Trigger Field Validation, there are also Hierarchical Level (HL) segment validations. The following validations are performed at run time:

  • No skips/no jumps. Schemas encountered where these restrictions are violated result in a run-time error.

  • All HL schema fields must be attributes. Checked at run time and result in an error if violations occur.

  • HL02 must be optional. Required because not all HLs have parents (for example, if they are top-level HLs). In the schemas, a syntax rule enforces the existence of this field.

  • HL04 must be "0" or "1". Enforced using a data type of Enumeration for this field, with values of 0 or 1.

  • Data out of order. HL segments must arrive in the proper hierarchical order. This is the same as the "no jumps" restriction, which basically requires that family tree branches must be followed to their conclusion before another tree can be entered (hierarchically speaking). Also, there is no returning after a branch change has occurred.

Related Topic

Set parse properties


Namespace Support

BizTalk Editor provides support for namespaces. An Extensible Markup Language (XML) namespace is a collection of names that can be used as element or attribute names in an XML document. The namespace qualifies element names uniquely to avoid conflicts between elements with the same name that may exist in the same document. The namespace is identified by some Universal Resource Identifier (URI), either as an Uniform Resource Locator (URL) or an Uniform Resource Name (URN).

In the case of non-XML data formats, the XDR schema is annotated with elements and attributes that belong to the BizTalk Server 2002 namespace. These namespace qualified elements and attributes contain information about the processing of non-XML formats, such as EDI and flat-file documents, to re-format them to an XML representation that BizTalk Server can use to transform, log, and track.

The following topics are covered in this section:

  • Namespace Declarations

  • Preserving Namespaces in Imported Files


Namespace Declarations

Namespaces that are declared in a specification are displayed on the Namespace tab of BizTalk Editor. The following table shows the prefixes and namespaces that appear on the Namespace tab by default when you open a specification in BizTalk Editor. You cannot edit these prefixes and namespaces.

Prefix | Namespace
(default) | urn:schemas-microsoft-com:xml-data
b | urn:schemas-microsoft-com:BizTalkServer
d | urn:schemas-microsoft-com:datatypes

Note

  • The following namespace is not supported by BizTalk Server 2002:

    SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

You can declare custom namespaces in a specification by typing a namespace prefix in the Prefix column and a namespace in the Uniform Resource Name column of the Namespace tab. BizTalk Editor does not validate the Uniform Resource Name that you enter for a namespace.

You can also add a custom annotation to any record and field. A custom annotation consists of a prefix-name pair and related value. The syntax for a prefix-name pair is shown in the following example:

prefix:name

On either the Declaration or Reference tab, type a prefix-name pair in the Property column and type a value in the Value column. Property values entered on the Declaration tab are global in scope, and property values entered on the Reference tab are local in scope. For more information about global and local scope, see Property Scope. For more information about adding custom annotations, see Add custom annotations.

Related Topics

Add custom annotations

Declare namespaces

Preserving Namespaces in Imported Files

Property Scope


Preserving Namespaces in Imported Files

You can import three types of files into BizTalk Editor: XML-Data Reduced (XDR) schemas, well-formed XML instances, and document type definitions (DTDs). BizTalk Editor handles existing namespaces and prefix-name pairs differently for each type of document.

Importing an XDR schema

When you import an XDR schema, existing namespaces are handled in the following manner:

  • Namespace declarations are preserved as custom namespaces and appear on the Namespace tab below the default namespaces.

  • Custom namespace prefixes (with the exception of those associated with the Name and Type properties) are preserved only if the associated namespace is declared.

Note

  • BizTalk Editor cannot import an XDR schema with a namespace prefix associated with the Name or Type property.

Importing a well-formed XML instance

When you import a well-formed XML document instance, namespace declarations are removed from the document, and the prefix-name separator symbol is changed from a colon (:) to an underscore (_) so that the original intention of the namespace prefix is not lost. For example:

prefix_name

Important

  • If you import a well-formed XML document instance that contains a namespace prefix-name pair, save the imported instance as a specification, and then try to validate the original document instance against the new specification, instance validation fails. In the new specification, delete the node that contains the prefix-name pair. For the parent record of that node (on the Declaration tab), select the Open value for the Model property and save the specification. You can validate the document instance against this specification.

Note

  • BizTalk Editor cannot import any document that contains a namespace prefix if the associated namespace has not been declared in the document.

Importing a DTD

When you import a DTD that contains a prefix-name pair, the separator symbol is changed from a colon (:) to an underscore (_). This is so that in terms of placement within the overall structure, the original intention of the prefix is not lost even though the prefix notation itself is not supported. For example:

prefix_name

Related Topic

Namespace Declarations


Adding SQL Annotations

You can specify an SQL annotation for any node in a specification. Specifying an SQL annotation on the Declaration tab creates an annotation that is global in scope. The annotation is saved within the ElementType or AttributeType declaration in the specification. Specifying an SQL annotation on the Reference tab creates an annotation that is local in scope. The annotation is saved within the Element or Attribute reference in the specification.

You can select an SQL annotation in the list that appears when you double-click an empty field in the Property column of either the Declaration tab or the Reference tab for a node in a specification. Enter a value for the SQL annotation in the corresponding field in the Value column. For all SQL annotations except sql:relationship and sql:xpath-query, the value is ordinary string data. For more information about adding SQL annotations and other custom annotations, see Add custom annotations.

The following list shows all the possible SQL annotations in BizTalk Editor:

  • sql:datatype

  • sql:field

  • sql:id

  • sql:id-prefix

  • sql:is-constant

  • sql:key-fields

  • sql:limit-field

  • sql:limit-value

  • sql:map-field

  • sql:is-mapping-schema

  • sql:overflow-field

  • sql:relation

  • sql:relationship

  • sql:target-namespace

  • sql:url-encode

  • sql:use-cdata

  • sql:xpath-query

The value of sql:relationship is one or more name-value pairs, and the name in each name-value pair must be one of four names: key, key-relation, foreign-key, or foreign-relation. The value of sql:xpath-query contains two parts: the first part is one or more name-value pairs that comprise an attribute or attributes, and the second part is the content of sql:xpath-query, represented as "content=...". These two parts are separated by the number sign (#).

The following table shows valid examples of the sql:relationship and sql:xpath-query SQL annotations.

SQL annotation | Example values
sql:relationship | key="CustomerID"
sql:relationship | key-relation="Cust"
sql:relationship | foreign-key="CustomerID"
sql:relationship | foreign-relation="Orders"
sql:xpath-query | mapping-schema="Schema.xml" #content=Employees

Notes

  • BizTalk Editor does not limit the selection of SQL annotations to only those that are appropriate in the current context. For example, sql:relationship and xpath-query are available on the Declaration tab, even though their use must be restricted to the Reference tab.

  • When you specify an SQL annotation, a namespace with an "sql" prefix and the corresponding Uniform Resource Name (URN) value is automatically declared on the Namespace tab.

  • When you copy or cut a node with SQL annotations specified on its Reference tab and then paste that node to a different location in the specification, the SQL annotations are not present in the new node.

Related Topics

Add custom annotations

Namespace Declarations

Property Scope


Creating XML and Native Instances

To ensure the success of Microsoft BizTalk Server 2002 in your production environment, BizTalk Editor provides a mechanism for you to test specifications prior to going live with them in your organization. Instance manipulation involves either testing an instance against a specification, or generating an instance based on a specification you have created in BizTalk Editor.

BizTalk Editor enables you to either create Extensible Markup Language (XML) instances or native instances. When working with flat files (both positional and delimited), it is not necessary to enter delimiter information. However, in the case of EDI documents, you must provide the delimiter to use.

Related Topics

Create a document instance

Create a native instance


Validating Instances and Specifications

BizTalk Editor enables you to validate a document instance. When validating a document instance against a specification with the standard set to X12, EDIFACT, or CUSTOM, the document instance must have a document structure that conforms to the standard of the specification. For example, you can validate an X12 document instance only against an X12 specification.

A document instance that contains a field with a blank attribute value ("") can be validated successfully against a specification regardless of the value that is set for the Minimum Length property for that field. For example, if a specification has a field with a Minimum Length property value set to 4, and you attempt to validate a document instance that has a corresponding field with a blank attribute value, the validation will not fail because of this mismatch. The reason for this is that the MSXML parser that underlies the validation engine treats an attribute with a blank value as though the attribute is not specified. This issue will be corrected for the next release of BizTalk Server.

Document Delimiters

BizTalk Editor enables you to specify delimiters during validation of instances and specifications. You can use the Document Delimiters tab to specify default delimiters to use during validation and can also specify whether or not to automatically display the Document Delimiters dialog box each time you validate a document instance. You can set delimiters once or have BizTalk Editor prompt you during each instance test for specific delimiters.

The following table lists the default values for delimiters.

Delimiter | Value
Record delimiter | ~ (0x7)
Field delimiter | * (0x2a)
Subfield delimiter | > (0x3e)
Escape | ? (0x3f)

Envelope information

Depending on the situation, you may not have to specify delimiters. For example, if an instance contains envelope information, which includes delimiter information, BizTalk Editor is able to automatically determine the correct delimiters to use. However, if header information is not found in the EDI instance being validated, BizTalk Editor will display the Document Delimiters dialog box enabling you to specify delimiters.

Validating documents in the middle of interchanges

BizTalk Editor will validate only the first document in a document instance that contains multiple documents. However, you can validate a document that exists in the middle of an interchange, meaning that it is not the first document in the interchange. To do this, you must remove the header information and all documents that precede the one being validated.

Optional and empty fields within records

If the document instance you are using has fields within a record that are both optional and empty, you must add a field delimiter before the record delimiter. For example, the following document instance contains a tilde (~) for the record delimiter. However, it also shows a plus sign (+) as the field delimiter for the first record. This requires that you set the Record Delimiter as ~ and the Field Delimiter as + in the Document Delimiters dialog box.

Document instance containing a tilde for the record delimiter

When you validate the previous document instance against the following specification, the following error appears:

While parsing record "Record1", the parser could not find the required leading delimiter: "+" (0x002b).
The parser failed to convert the document due to processing errors. See the following messages for details.

Validating a document instance against a specification

To resolve this issue, add a "+" between the "TTT" and the "~" in the document instance.

  • It is strongly recommended that before you use a document instance in a production environment, you validate the instance against its source specification and correct any problems displayed on the Warnings tab.

Microsoft BizTalk Accelerator for HIPAA schemas

In BizTalk Editor, there is an option to set subdocument_creation_break to "yes" for BizTalk Accelerator for HIPAA schemas. In this instance, the parser will generate several XML document instances that are contained in the original payload. In these cases, validation is identical to that for EDI validation. For example, interchanges are split and schemas are validated against the first document in the resultant set of split documents.


Why Perform BizTalk Editor Tasks

This section provides a quick reference about why you perform BizTalk Editor tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
  • Change BizTalk Editor options
 If you want to create a new field as an element. Or, if you want to specify default document delimiters to use during instance testing. In addition, this procedure also describes how to automatically display the Document Delimiters dialog box each time you validate a document instance.
Create and Validate Specifications:
  • Create a specification based on a standard
 If you need to set up a process with a trading partner and know you need to use standards, such as X12 or EDIFACT.

Also, if you do not have trading partner agreements set up, but anticipate needing to use standards that are published. For example, you might be planning to set up your organization as a Web service.
  • Create a specification based on a flat file
 If you are dealing with legacy systems that use flat files. Or, if you use SAP (or similar applications that standardize on the use of flat files) or have trading partners that do.
  • Create a specification based on an empty template
 This type of template is ideal if you are primarily doing enterprise application integration (EAI) within your organization. This template enables you to start with a single root node and build the structure you need from the "ground up."
  • Create a specification based on an existing specification
 You might work with an existing specification if performing EAI or business-to-business integration tasks is new to you. Or, you might be exchanging data with an organization that has an existing specification that can easily be modified, saving you time and effort.
  • Create a specification based on an imported file
 If you need to work with an existing specification.
  • Create a specification based on a Microsoft Office file
 If you are primarily working within your organization or with trading partners that use applications such as Microsoft Excel for capturing data. For example, an expense report might contain a macro that enables employees to enter expenses and you create a specification to correspond to the data being entered.
  • Validate a specification
 To ensure that the records and fields you have defined in your specification are valid. Although BizTalk Editor provides feedback regarding whether or not your actions are valid, you might import a file that contains an invalid structure. The only time you are warned about the validity of a structure is when you validate the specification.
Open, Save, and Export Specifications:
  • Open existing specifications from a local drive
 If you want to work on a local copy of a specification. For example, you might want to make some modifications and then test the specification without impacting the collaborative copy that is stored in Web Distributed Authoring and Versioning (WebDAV).
  • Open existing specifications from WebDAV
 If you need to work on the collaborative copy of a specification that others can also access and modify. This is the file that BizTalk Messaging Manager uses when processing transactions.
  • Open existing specifications from folders
 If you want to work on a local copy of a specification. For example, you might want to make some modifications and then test the specification without impacting the collaborative copy that is stored in WebDAV.
  • Save new specifications
 If you want to save a local copy of a specification that you just created. For example, you might want to save a specification that you just created without impacting the collaborative copy that is stored in WebDAV.
  • Save existing specifications
 If you want to save a local copy of a specification that you modified. For example, you might want to save a specification that you have modified without impacting the collaborative copy that is stored in WebDAV.
  • Store XDR schema to WebDAV
 You cannot directly store pure XML-Data Reduced (XDR) schemas (non-BizTalk Server schemas) to WebDAV using BizTalk Editor. If you need to, make the XDR schema available to BizTalk Messaging Manager through WebDAV. This will also make the file available to others to use.
  • Store specifications
 If you need to make a specification available to BizTalk Messaging Manager through WebDAV. This will also make the file available to others to use.
  • Export XDR schemas
 If you need to send a BizTalk Server specification to a trading partner that does not have BizTalk Server. The BizTalk Server specification annotations are removed during the export process, making it easier for the trading partner use the final schema.
  • Export XSD schemas
 If you need to send the data that your specification represents to a trading partner that works in Extensible (XML) Structure Definitions (XSD).
Manage Records and Fields:
  • Add new records to the root node

  • Add new fields to the root node

  • Add new records to existing records

  • Add new fields to records

  • Insert records

  • Insert fields
 To build a new structure for a specification or modify an existing structure.
  • Create a new field as an element
 If all the new fields you will be adding need to repeat, or need to have structure.
  • Change fields from attributes to elements
 If you have an existing field that needs to repeat, or needs to have structure. Elements have structure, whereas attributes do not.
  • Change fields from elements to attributes
 If you do not want to allow a field to have structure.
  • Move records within a specification

  • Move fields within a specification

  • Move records from one specification to another

  • Move fields from one specification to another
 To change the structure of one or more specifications. Moving records and fields from one specification to another, rather than adding them and adding properties, saves time.
  • Copy records within a specification

  • Copy fields within a specification

  • Copy records from one specification to another

  • Copy fields from one specification to another
 To change the structure of one or more specifications. Copying records and fields, rather than creating new ones, saves time.
  • Create cyclical references
 If you know that there is a recursive (meaning that a node contains itself as a descendent) structure in the data BizTalk Server will be processing. Recursive structures are common when dealing with items that have many components and subcomponents.
  • Create a new instance of an existing record
 If you want to quickly recreate the same structure as an existing record.
  • Create a new instance of an existing element field
 If you want to quickly recreate the same structure as an existing field.
Specify Properties for Records and Fields:
  • Set document delimiters
 If you have a delimited structure, then you must set document delimiters. Otherwise, BizTalk Server is not able to process the data.
  • Set declaration properties
 To control the properties of the data structure at a global level.
  • Set reference properties
 To control the properties of the data structure at a local level.
  • Set parse properties
 To provide instructions regarding how to handle converting non-XML data.
  • Declare namespaces
 To assign annotations to various parts of your specification. This overrides the use of the default namespace that may be associated with the specification.
  • Add custom annotations
 To mark-up a specification with specific instructions. For example, if you have a custom parser, you might want to add custom annotations. Annotations must be part of a namespace.
  • Set dictionary properties
 Every work item in BizTalk Server has an associated collection of properties that describe the work item. If you want to add content to the collection, then you need to set dictionary properties. You would most likely add routing or envelope-related properties to the property collection.
  • Add a custom dictionary property
 Set a custom dictionary property. See the previous explanation for the "Set dictionary properties" task.
  • Select codes
 If your specification is based on an X12 or EDIFACT structure, you will want to select codes to set the Data Type property for a field to Enumeration and set the Data Type Value to a valid code.
  • Clear codes
 Remove codes added to a field.
  • Automatically calculate field positions
 If you have a specification with a positional structure and have predefined all the Maximum Length values, use this to automatically calculate the start and end positions for each field.
Edit Notes and Syntax Rules:
  • Enter Record Notes
 Provide documentation for yourself or someone else that might work on the specification.
  • View Syntax Rules
 This applies only to specifications based on X12 structure. Use this if you need to map to or from an X12 specification and you want to ensure that the specification does not violate any standard syntax rules.
  • Enter Field Notes
 Provide documentation for yourself or someone else that might work on the specification.
Manage Document Instances:
  • Create a document instance
 To test a specification against an XML or non-XML data instance.
  • Create a native instance
 To test a specification against a non-XML data instance.
  • Validate a document instance
 To ensure that the specification is compatible with the data that will be passed through it.
  • Manage Invalid Character Maps
 If there are restrictions regarding the type of characters the consuming application can handle, you will want to specify the characters that are invalid.
Manage Views and Use Shortcut Keys:
  • Expand tree items
 To view all the records and fields in a specification from the viewpoint of the root node record or simply the records and fields from the viewpoint of a single record.
  • Collapse tree items
 To view only the root node record and/or parent records.
  • View property values
 To view the properties for a record or field that are associated with the Declaration, Reference, Parse, Namespace, Dictionary, or Code List tab.
  • Change text sizes
 To increase or decrease the font size of text in BizTalk Editor.
  • BizTalk Editor Shortcut Keys
 To use shortcut keys, rather than a mouse, to accomplish tasks.


How to Perform BizTalk Editor Tasks

This section provides task-specific information about how to create a specification. It is highly recommended that you review About BizTalk Editor to understand fully the relationship between records and fields and how to specify properties for the type of specification that you want to create.

The following topics are covered in this section:

  • Change BizTalk Editor options

  • Create and Validate Specifications

  • Open Specifications

  • Save, Export, and Close Specifications

  • Manage Records and Fields

  • Specify Properties for Records and Fields

  • Edit Notes and View Syntax Rules

  • Manage Document Instances

  • Manage Invalid Character Maps

  • Manage Views

  • BizTalk Editor Shortcut Keys


Change BizTalk Editor options

  1. To view or change options in the BizTalk Editor Options dialog box, on the Tools menu, click Options.

  2. On the General tab, you can select the Create a new field as an element check box.

    For information about this tab, see Create a new field as an element.

  3. On the Document Delimiters tab, you can specify default delimiters to use during instance testing and can also specify whether or not to automatically display the Document Delimiters dialog box each time you validate a document instance.

    For more information about this tab, see Set document delimiters.

Related Topics

Create a new field as an element

Set document delimiters


Create and Validate Specifications

This section describes how to create a specification depending on the type of data you are using. For example, if you are working with a delimited flat file, you will need to create a specification based on that flat file. It is important to understand issues with invalid Extensible Markup Language (XML) name characters when you work with specifications because if you use an invalid Unicode character in an XML name, that character is translated into an escaped numeric entity when you view it in the specification tree. For more information, see Invalid XML Name Characters.

The following procedures are covered in this section:

  • Create a specification based on a standard

  • Create a specification based on a flat file

  • Create a specification based on an empty template

  • Create a specification based on an existing specification

  • Create a specification based on an imported file

  • Create a specification based on a Microsoft Office file

  • Validate a specification


Create a specification based on a standard

  1. On the File menu, click New.

    The New Document Specification dialog box appears.

  2. Click XML, X12, or EDIFACT, and then click OK.

    If you select EDIFACT or X12, you must also select a version. Click the folder for the version that you want and click OK.

  3. Click the specification type and click OK.

  4. Delete records, if necessary.

  5. Delete fields, if necessary.

  6. Clear codes, if necessary.

  7. Save the new specification.

Important

  • When the X12 templates included with the BizTalk Server installation are used in BizTalk Editor, you might encounter an error message similar to the following:

    The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

    The X12 templates use the implied decimal data type Nx. If the input data contains a decimal point, output will not match the N custom data type (which means no decimal point) and will create invalid instances in the intermediate XML file. In this release of BizTalk Server, the serializer might not detect whether the intermediate XML file contains a decimal point for data type N output. To resolve this issue, you must manually change the implied decimal data type in the X12 templates to any other numeric data type.

Note

  • A restriction to the kinds of instance structure permutation supported by the X12 parser is that there cannot be generational skips in Hierarchy Level (HL) segments. This is a restriction whereby any HL segment/loop must be exactly one level deeper from the root than its parent HL segment/loop, if it has a parent HL. For example, HL/NM1/HL is not supported. In other words, a given sequence of 'x' nested HLs must span exactly 'x' generations of depth in the tree.

Related Topics

Manage Records and Fields

Specify Properties for Records and Fields

Understanding Specifications


Create a specification based on a flat file

  1. On the File menu, click New.

    The New Document Specification dialog box appears.

  2. Click Blank Specification and click OK.

  3. Highlight the root node and click the Reference tab.

  4. Double-click the Value field in the Standard row.

  5. In the Standard list, click CUSTOM.

  6. Press ENTER.

  7. Click Yes to confirm the change.

  8. Add new records to the root node.

  9. Add new records to existing records.

  10. Add new fields to the root node.

  11. Add new fields to records.

  12. Specify properties for records and fields.

  13. Save the new specification.

Notes

  • On the Parse tab, you must set the Structure property of the root node to Delimited if your flat file is both delimited and positional. Additional record properties are set to either Delimited or Positional, as required. For more information, see Working with Positional and Delimited Flat Files.

  • Positional flat-file parsing does not suppress an optional element if it does not contain data similar to delimited flat-file parsing. Also, an element without a value will affect the mapping result.

  • Flat files based on the UTF-8 code page are not supported by BizTalk Editor.

International Issue

  • Positional flat files can include 2-byte or 1-byte characters for one code page. Most applications that support positional (fixed length) flat files expect the string data to be aligned in bytes, not characters. This causes issues in handling string data in positional flat files. To resolve this issue, treat positional files with a mix of double-byte character set (DBCS) and single-byte character set (SBCS) characters as delimited.

Related Topics

Manage Records and Fields

Specify Properties for Records and Fields

Understanding Specifications

Working with Positional and Delimited Flat Files


Create a specification based on an empty template

  1. On the File menu, click New.

    The New Document Specification dialog box appears.

  2. Click Blank Specification and click OK.

  3. Add new records to the root node.

  4. Add new records to existing records.

  5. Add new fields to the root node.

  6. Add new fields to records.

  7. Specify properties for records and fields.

  8. Save the new specification.

Related Topics

Manage Records and Fields

Specify Properties for Records and Fields

Understanding Specifications


Create a specification based on an existing specification

  1. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  2. Browse to a folder that contains an existing specification.

  3. Click a file from the list and click Open.

  4. Modify the specification as needed.

  5. On the File menu, click Save As.

    The Save Document Specification As dialog box appears.

  6. In the File Name box, type a name for the specification.

  7. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to create a specification associated with ASCII characters, in the Encoding list, click UTF-8. For specifications associated with double-byte characters, in the Encoding list, click UTF-8 or Unicode.

  8. Manage Records and Fields.

  9. Save the new specification.

Related Topics

Code List Values and Descriptions

Manage Records and Fields


Create a specification based on an imported file

  1. On the Tools menu, click Import.

    The Select Import Module dialog box appears.

  2. Click Well-Formed XML Instance, Document Type Definition, or XDR Schema, and then click OK.

    Important

    • You cannot import a well-formed XML instance if it contains an XDR schema.

    • If you are importing a Microsoft Office file, click Well-Formed XML Instance.

    • If you are importing an XML-Data Reduced (XDR) file, click XDR Schema.
  3. In the Import dialog box, browse to the folder that contains the file that you want to import, click the file, and then click Open.

    Important

    • If BizTalk Editor cannot determine which element should be the root node, it displays the Select Root Element dialog box. Select a root element from the Root elements list, and then click OK. For more information, see Importing Files.

    • When you open a non-BizTalk Server XDR schema in BizTalk Editor, you will see error and/or warning messages if element groups and/or namespaces are present in the schema.
  4. Add new records to the root node.

  5. Add new records to existing records.

  6. Add new fields to the root node.

  7. Add new fields to records.

  8. Specify properties for records and fields.

  9. Save the new specification.

Important

  • If a schema contains a namespace Uniform Resource Name (URN) that begins with "x-schema:", you might not be able to open it with BizTalk Editor. You should remove the x-schema reference and then import the file into BizTalk Editor.

  • BizTalk Editor cannot import a document type definition (DTD) and/or an XML-Data Reduced (XDR) schema that contains a cyclical reference involving the root node. BizTalk Editor can import a well-formed XML document that contains a cyclical reference involving the root node, although it displays a warning indicating that cyclical references cannot involve the root node of a document. For more information, see Cyclical References.

  • If you import a file and need mixed content support, the instance being imported must contain mixed content. If it does not contain mixed content, the Content value on the Declaration tab will not be set to Mixed.

Related Topics

Importing Files

Manage Records and Fields

Specify Properties for Records and Fields


Create a specification based on a Microsoft Office file

  1. On the Tools menu, click Import.

    The Select Import Module dialog box appears.

  2. Click Well-Formed XML Instance, and then click OK.

  3. In the Import dialog box, browse to the folder that contains the file that you want to import, click the file, and then click Open.

    Important

    • If BizTalk Editor cannot determine which element should be the root node, it displays the Select Root Element dialog box. Select a root element from the Root elements list, and then click OK. For more information, see Importing Files.
  4. Add new records to the root node.

  5. Add new records to existing records.

  6. Add new fields to the root node.

  7. Add new fields to records.

  8. Specify properties for records and fields.

  9. Save the new specification.

Related Topics

Importing Files

Manage Records and Fields

Specify Properties for Records and Fields


Validate a specification

  1. Open a specification or import a schema.

    For more information, see Open Specifications or Create a specification based on an imported file.

  2. On the Tools menu, click Validate Specification.

The Warnings tab displays warnings indicating any problems that might exist with the specification's structure. You can double-click a warning and the record or field, and the associated property, are displayed in red in the panes above.

Related Topics

Create a specification based on an imported file

Open Specifications


Open Specifications

The following procedures are covered in this section:

  • Open existing specifications from a local drive

  • Open existing specifications from WebDAV

  • Open existing specifications from folders


Open existing specifications from a local drive

  1. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  2. Browse to the folder that contains the specification that you want to open, click the specification, and then click Open.

Note

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Open existing specifications from WebDAV


Open existing specifications from WebDAV

  1. On the File menu, click Retrieve From WebDAV.

    The Retrieve from WebDAV dialog box appears.

  2. In the Server list, type the server name and press ENTER.

    You also can select a server name from the list.

    Important

    • If your Proxy Server Port is not 80, you need to type the following in the Server list, http://<server name>:<port number>, to access files stored in WebDAV.

    • You cannot retrieve files on a secure server. For example, if the server is https://<server name>/biztalkserverrepository, you will not be able to access any files.
  3. Browse to the folder that contains the specification that you want to open, click the specification, and then click Open.

Important

  • If you get an error message, such as "No BizTalk Server Repository was found on http://<server name>/BizTalkServerRepository/DocSpecs," when you are trying to opening existing specifications from WebDAV, re-register msdaipp.dll and then restart your computer. For more information about how to re-register msdaipp.dll, see Re-register msdaipp.dll to retrieve or store specifications in WebDAV.

  • Notes

  • You might experience a delay the first time you connect to a remote WebDAV server during a session.

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topics

Open existing specifications from a local drive

Troubleshooting BizTalk Editor and BizTalk Mapper


Open existing specifications from folders

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.

  2. Locate the file you want to view in BizTalk Editor.

    If necessary, click Restore Down to reduce the window size so that you can see the BizTalk Editor window.

  3. Drag the file to the specification tree pane.

Note

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.


Save, Export, and Close Specifications

The following procedures are covered in this section:

  • Save new specifications

  • Save existing specifications

  • Store XDR schema to WebDAV

  • Store specifications

  • Export XDR schemas

  • Export XSD schemas

  • Close specifications


Save new specifications

  1. On the File menu, click Save As.

    The Save Document Specification As dialog box appears.

  2. In the File Name box, type a name for the file.

  3. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to save a specification associated with ASCII characters, in the Encoding list, click UTF-8. For specifications associated with double-byte characters, in the Encoding list, click UTF-8 or Unicode.

Note

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.


Save existing specifications

  • On the File menu, click Save.

Notes

  • When you save a file, BizTalk Editor stores the file on your hard disk. To save a file to WebDAV, you must have permission to store the file on the server.

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Store specifications


Store XDR schema to WebDAV

You cannot directly store pure XDR schemas (non-BizTalk Server schemas) to WebDAV using BizTalk Editor. Instead, you must perform the following procedure.

  1. Complete the steps for Save new specifications or Save existing specifications.

  2. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.

  3. Browse to the WebDAV location where you want to store the file.

  4. Browse to the location where you saved the pure XDR schema.

  5. Drag the file from the location you saved it in to the WebDAV folder.

International Issues

  • Files can be saved only in Unicode encodings in the WebDAV repository. However, the WebDAV repository cannot store files with names in different code pages.

  • WebDAV does not support Unicode characters in file names.

  • Make sure that your system locale is set to your language. For example, international users who install the English version of BizTalk Server 2002 on a computer running the English version of Windows, and want to name files with characters that are not supported in the Latin I code page (Windows 1252 including English), must change the system locale to their user locale.

  • You cannot store files with double-byte character set (DBCS) file names if you have an incorrect locale setting. To correct this problem, see ???.xml appears in the WebDAV dialog box.


Store specifications

  1. On the File menu, click Store to WebDAV.

    The Store to WebDAV dialog box appears.

  2. In the Server list, type the server name and press ENTER.

    You also can select a server name from the list.

    Important

    • If your Proxy Server Port is not 80, you need to type the following in the Server list, http://<server name>:<port number>, to store files in WebDAV.

    • You cannot store files on a secure server. For example, if the server is https://<server name>/biztalkserverrepository, you will not be able to store any files.
  3. Browse to the folder in which you want to store your specification.

  4. In the File Name box, type the name of the file.

  5. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to store a specification associated with ASCII characters, in the Encoding list, click UTF-8. For specifications associated with double-byte characters, in the Encoding list, click UTF-8 or Unicode.

International Issues

  • Files can be saved only in Unicode encodings in the WebDAV repository. However, the WebDAV repository cannot store files with names in different code pages.

  • WebDAV does not support Unicode characters in file names.

  • Make sure that your system locale is set to your language. For example, international users who install the English version of BizTalk Server 2002 on a computer running the English version of Windows, and want to name files with characters that are not supported in the Latin I code page (Windows 1252 including English), must change the system locale to their user locale.

  • You cannot store files with double-byte character set (DBCS) file names if you have an incorrect locale setting. To correct this problem, see ???.xml appears in the WebDAV dialog box.

Important

  • If you get an error message, such as "No BizTalk Server Repository was found on http://<server name>/BizTalkServerRepository/DocSpecs," when you are trying to store specifications to WebDAV, re-register msdaipp.dll and then restart your computer. For more information about how to re-register msdaipp.dll, see Re-register msdaipp.dll to retrieve or store files in WebDAV.

Notes

  • You might experience a delay the first time you connect to a remote WebDAV server.

  • When you store a file to WebDAV, BizTalk Editor stores the file on a server. To save a file to your hard disk, on the File menu, click Save As.

  • Once you install BizTalk Server 2002, if you open a specification that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topics

Save existing specifications

Save new specifications

Troubleshooting BizTalk Editor and BizTalk Mapper


Export XDR schemas

  1. On the Tools menu, click Export XDR Schema.

    The Export XDR schema as dialog box appears.

  2. Browse to the location to which you want to export the XML-Data Reduced (XDR) file.

  3. In the File name box, type a name for the file.

  4. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to export a specification associated with ASCII characters, in the Encoding list, click UTF-8. For specifications associated with double-byte characters, in the Encoding list, click UTF-8 or Unicode.

Related Topics

Open Specifications

Export XSD schemas


Export XSD schemas

Before you export an Extensible (XML) Structure Definitions (XSD) schema, you should save the file.

  1. On the Tools menu, click Export XSD Schema.

    The Export XSD schema as dialog box appears.

  2. Browse to the location to which you want to export the XSD file.

  3. In the File name box, type a name for the file and click Save.

Notes

  • If your specification contains a target namespace and you use the Export XSD Schema functionality to export the file, the exported XSD schema will not contain a target namespace. To resolve this issue, open the exported XSD file in Notepad and manually add the target namespace to it.

  • Exported XSD files are in UTF-16 format by default.

Related Topics

Open Specifications

Export XDR schemas


Close specifications

  • On the File menu, click Close.


Manage Records and Fields

The following procedures are covered in this section:

  • Add new records to the root node

  • Add new fields to the root node

  • Add new records to existing records

  • Add new fields to records

  • Insert records

  • Insert fields

  • Create a new field as an element

  • Change fields from attributes to elements

  • Change fields from elements to attributes

  • Move records within a specification

  • Move fields within a specification

  • Move records from one specification to another

  • Move fields from one specification to another

  • Copy records within a specification

  • Copy fields within a specification

  • Copy records from one specification to another

  • Copy fields from one specification to another

  • Rename a single record

  • Rename a single field

  • Rename all records that have the same name

  • Delete records

  • Delete fields

  • Create cyclical references

  • Create a new instance of an existing record

  • Create a new instance of an existing element field


Add new records to the root node

  1. Click the root node.

  2. On the Edit menu, click New Record.

    A child record is inserted after the last node in the specification tree.

  3. Type a name for the record and press ENTER.

Notes

  • For a non-XML file such as a flat file, you can type a Source Tag Identifier property to identify the tag in the non-XML source file.

  • Sibling records cannot have the same name.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topic

Specify Properties for Records and Fields


Add new fields to the root node

  1. Click the root node.

  2. On the Edit menu, click New Field.

    A child field is inserted after the last node in the specification tree.

  3. Type a name for the field and press ENTER.

Notes

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Change fields from elements to attributes

Create a new field as an element

Specify Properties for Records and Fields


Add new records to existing records

  1. Click a record.

  2. On the Edit menu, click New Record.

    A child record is inserted directly after the selected record or after the last child node of the selected record.

  3. Type a name for the record and press ENTER.

Notes

  • For a non-XML file such as a flat file, you can type a Source Tag Identifier property to identify the tag in the non-XML source file.

  • Sibling records cannot have the same name.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topic

Specify Properties for Records and Fields


Add new fields to records

  1. Click a record.

  2. On the Edit menu, click New Field.

    A child field is inserted directly after the selected record or after the last child node of the selected record.

  3. Type a name for the field and press ENTER.

Notes

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Change fields from elements to attributes

Create a new field as an element

Specify Properties for Records and Fields


Insert records

  1. Click a record.

  2. On the Edit menu, click Insert Record.

    A sibling record is inserted directly after the selected record or after the last child node of the selected record.

  3. Type a name for the record and press ENTER.

Notes

  • Sibling records cannot have the same name.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topic

Specify Properties for Records and Fields


Insert fields

  1. Click the record or field after which you want to insert a field.

  2. On the Edit menu, click Insert Field.

    A sibling field is inserted directly after the selected record or after the last child node of the selected record.

  3. Type a name for the field and press ENTER.

Notes

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Change fields from elements to attributes

Create a new field as an element

Specify Properties for Records and Fields


Create a new field as an element

  1. On the Tools menu, click Options.

    The BizTalk Editor Options dialog box appears.

  2. Select the Create a new field as an element check box and click OK.

Notes

  • While this check box is cleared, fields are created as attributes. However, if you select the Create a new field as an element check box, all new fields are created as elements.

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

Related Topic

Change fields from elements to attributes


Change fields from attributes to elements

  1. Click a field in the specification tree.

  2. On the Declaration tab, double-click the Value field in the Type row.

    The current setting is Attribute.

  3. In the Type list, click Element and press ENTER.

  4. Click Yes to confirm the change.

Note

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

Related Topics

Change fields from elements to attributes

Create a new field as an element


Change fields from elements to attributes

  1. Click a field in the specification tree.

  2. On the Declaration tab, double-click the Value field in the Type row.

    The current setting is Element.

  3. In the Type list, click Attribute and press ENTER.

  4. Click Yes to confirm the change.

Note

  • Sibling fields cannot have the same name unless one field has its Type property set to Attribute and the other has its Type property set to Element.

Related Topic

Change fields from attributes to elements


Move records within a specification

  1. Click the root node.

  2. On the View menu, click Expand Tree Items.

  3. Click the record that you want to move and drag it to another node in the tree.

    When you release the mouse button, if the mouse pointer is in the upper half of the highlighted node text, the record is inserted above the node as a sibling. If the mouse pointer is in the lower half of the highlighted node text, the record is inserted below the node as a sibling. If the mouse pointer is to the right of highlighted node text, the record is inserted below the highlighted record as a child.

Related Topics

Copy records from one specification to another

Copy records within a specification

Move records from one specification to another


Move fields within a specification

  1. Click the root node.

  2. On the View menu, click Expand Tree Items.

  3. Click the field that you want to move and drag it to another node in the tree.

    When you release the mouse button, if the mouse pointer is in the upper half of the highlighted node text, the field is inserted above the node as a sibling. If the mouse pointer is in the lower half of the highlighted node text, the field is inserted below the node as a sibling. If the mouse pointer is to the right of highlighted node text, the field is inserted below the record as a child.

Related Topics

Copy fields from one specification to another

Copy fields within a specification

Move fields from one specification to another


Move records from one specification to another

  1. Click the root node in the specification that contains the record that you want to move.

  2. On the View menu, click Expand Tree Items.

  3. Click the record that you want to move and, on the Edit menu, click Cut.

  4. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

    You must open a second instance of BizTalk Editor to open a different specification.

  5. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  6. Browse to the folder that contains the specification to which you want to move the record.

  7. Click the file in the list and click Open.

  8. Click the root node in the specification.

  9. On the View menu, click Expand Tree Items.

  10. Click the root node, a record, or a field after which you want to insert the record.

  11. On the Edit menu, click Paste.

Note

  • If you move a record that has the same name as an existing record, BizTalk Editor automatically adds a number to the end of the record's name.

Related Topics

Copy records from one specification to another

Copy records within a specification

Move records within a specification


Move fields from one specification to another

  1. Click the root node in the specification that contains the field that you want to move.

  2. On the View menu, click Expand Tree Items.

  3. Click the field that you want to move and, on the Edit menu, click Cut.

  4. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

    You must open a second instance of BizTalk Editor to open a different specification.

  5. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  6. Browse to the folder that contains the specification to which you want to move the record.

  7. Click the file in the list and click Open.

  8. Click the root node in the specification in which you want to move the field.

  9. On the View menu, click Expand Tree Items.

  10. Click the root node, record, or field after which you want to insert the field.

  11. On the Edit menu, click Paste.

Note

  • If you move a field that has the same name as an existing field, BizTalk Editor automatically adds a number to the end of the field's name.

Related Topics

Copy fields from one specification to another

Copy fields within a specification

Move fields within a specification


Copy records within a specification

  1. Click the root node.

  2. On the View menu, click Expand Tree Items.

  3. Click the record that you want to copy and, on the Edit menu, click Copy.

  4. Click the node after which you want to insert the record and, on the Edit menu, click Paste.

    If the selected node is a record, a child record is inserted directly after the selected node. If the selected node is a field, a sibling record is inserted directly after the selected node.

Important

  • If the record you are copying is the root node record, all child records and fields are copied, but not the root node record itself. You have to manually create that record if you want to have it included in the specification.

Related Topics

Copy records from one specification to another

Move records from one specification to another

Move records within a specification


Copy fields within a specification

  1. Click the root node.

  2. On the View menu, click Expand Tree Items.

  3. Click the field that you want to copy and, on the Edit menu, click Copy.

  4. Click the node after which you want to insert the field and, on the Edit menu, click Paste.

    If the selected node is a record, a child field is inserted directly after the selected node. If the selected node is a field, a sibling field is inserted directly after the selected node.

Related Topics

Copy fields from one specification to another

Move fields from one specification to another

Move fields within a specification


Copy records from one specification to another

  1. Click the root node in the specification that contains the record that you want to copy.

  2. On the View menu, click Expand Tree Items.

  3. Click the record that you want to copy and, on the Edit menu, click Copy.

  4. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

    You must open a second instance of BizTalk Editor to open a different specification.

  5. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  6. Browse to the folder that contains the specification to which you want to copy the record.

  7. Click the file in the list and click Open.

  8. Click the root node in the specification in which you want to copy the record.

  9. On the View menu, click Expand Tree Items.

  10. Click the root node, record, or field after which you want to insert the record and, on the Edit menu, click Paste.

    If the selected node is a record, a child record is inserted directly after the selected node. If the selected node is a field, a sibling record is inserted directly after the selected node.

Important

If the record you are copying is the root node record, all child records and fields are copied, but not the root node record itself. You have to manually create that record if you want to have it included in the specification.

Note

  • If you copy a record that has the same name as an existing record, BizTalk Editor automatically adds a number to the end of the record's name.

Related Topics

Copy records within a specification

Move records from one specification to another

Move records within a specification


Copy fields from one specification to another

  1. Click the root node in the specification that contains the field that you want to copy.

  2. On the View menu, click Expand Tree Items.

  3. Click the field that you want to copy and, on the Edit menu, click Copy.

  4. Click Start, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

    You must open a second instance of BizTalk Editor to open a different specification.

  5. On the File menu, click Open.

    The Open Document Specification dialog box appears.

  6. Browse to the folder that contains the specification to which you want to move the field.

  7. Click the file in the list and click Open.

  8. Click the root node in the specification to which you want to copy the field.

  9. On the View menu, click Expand Tree Items.

  10. Click the root node, record, or field after which you want to paste the record and, on the Edit menu, click Paste.

    If the selected node is a record, a child field is inserted directly after the selected node. If the selected node is a field, a sibling field is inserted directly after the selected node.

Note

  • If you copy a field that has the same name as an existing field, BizTalk Editor automatically adds a number to the end of the field's name.

Related Topics

Copy fields within a specification

Move fields from one specification to another

Move fields within a specification


Rename a single record

  1. Click the record that you want to rename.

  2. On the Edit menu, click Rename.

  3. Type a new name for the record and press ENTER.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Rename all records that have the same name

Rename a single field


Rename a single field

  1. Click the field that you want to rename.

  2. On the Edit menu, click Rename.

  3. Type a new name for the field and press ENTER.

Notes

  • Fields that are elements cannot have the same name as an existing record.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Rename all records that have the same name

Rename a single record


Rename all records that have the same name

  1. Click any record that has the name that you want to change.

  2. On the Edit menu, click Rename All <record name>.

  3. Type a new name for the records.

    All records that have the same name are renamed.

Notes

  • This command is unavailable on the Edit menu unless there are at least two records with the same name.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Rename a single field

Rename a single record


Delete records

  1. Click the record that you want to delete.

  2. On the Edit menu, click Delete.

  3. Click Yes in the confirmation dialog box.

Caution

  • When you delete a record, all child records and fields are also deleted.

Related Topic

Delete fields


Delete fields

  1. Click the field that you want to delete.

  2. On the Edit menu, click Delete.

  3. Click Yes in the confirmation dialog box.

Related Topic

Delete records


Create cyclical references

  1. Select a record below which you want to create a cyclical reference.

    This is the base record.

  2. On the Edit menu, click New Record.

  3. Name the new record the same name as the base record and press ENTER.

    A cyclical reference Cyclical reference icon is created.

  4. On the Declaration tab, double-click the Value field in the Cycle Count row.

  5. Type a number from 1 to 7 and press ENTER.

Important

  • The Minimum Occurrences property on the Reference tab for the cyclical reference node must be set to 0. Setting it to 1 will cause an infinite loop.

Note

  • You cannot use cyclic references in non-XML specifications. Make sure that you use an XML-based specification.

Related Topic

Cyclical References


Create a new instance of an existing record

  1. Click a node where you want to create a new instance of an existing record.

  2. On the Edit menu, click New Record or Insert Record.

    Note

    • If you selected a field in step 1, New Record is unavailable on the Edit menu.
  3. Name the new record the same name as the existing record and press ENTER.

    You have created two instances of the same record.

Important

  • You cannot name a new record instance the same name as a sibling record.

  • If you name a new record the same name as a parent record, you create a cyclical reference, not a new instance of the existing record. For more information, see Cyclical References.

Notes

  • If you click New Record, the new record instance is inserted as a descendant of the record that you selected.

  • If you click Insert Record, the new record instance is inserted as a sibling of the record or field that you selected.

  • The node structure below instances of a record is identical; if you remove or add a node to one instance of a record, that change is automatically reflected in all other instances of the record. Some properties of record instances are identical, and other properties can be set independently for each instance. For more information about which properties are identical across record instances and which are not, see Property Scope.

  • You cannot name an existing record the same name as another existing record.

  • An alternative way to create a new instance of an existing record is to press the CTRL key and drag an existing record to the right of the node below which you want to insert the new record instance.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Cyclical References

Property Scope


Create a new instance of an existing element field

  1. Select a node where you want to create a new instance of an element field.

    Note

    • You can create multiple instances of fields only of type Element (on the Declaration tab). You cannot create multiple instances of fields of type Attribute. If you create two or more attribute fields with the same name, the fields remain completely independent of each other.
  2. On the Edit menu, click New Field or Insert Field.

    Note

    • If you selected a field in step 1, New Field is unavailable on the Edit menu.
  3. Name the new field the same name as the existing field and press ENTER.

    You have created two instances of the same field.

Important

  • You cannot name a new element field instance the same name as a sibling element field instance.

Notes

  • If you click New Field, the new field instance is inserted as a descendant of the record that you selected.

  • If you click Insert Field, the new field instance is inserted as a sibling of the record or field that you selected.

  • Some properties of field instances are identical, and other properties can be set independently for each instance. For more information about which properties are identical across field instances and which are not, see Property Scope.

  • You cannot name an existing field the same name as another existing field, unless one field has its Type property set to Attribute and the other field has its Type property set to Element.

  • An alternative way to create a new instance of an existing element field is to press the CTRL key and drag an existing element field to the right of the node below which you want to insert the new field instance.

International Issue

  • If you are using an Input Method Editor (IME) to enter Korean characters for record or field names, BizTalk Editor enables duplicate names even though an error message appears when you try to rename a record or field to an existing name. BizTalk Editor also enables entering invalid record or field names when using the Korean IME that would otherwise not be allowed. To resolve this issue, delete the invalid record or field.

Related Topics

Cyclical References

Property Scope


Specify Properties for Records and Fields

This section includes information about the following topics:

  • Set document delimiters

  • Set declaration properties

  • Set reference properties

  • Set parse properties

  • Declare namespaces

  • Add custom annotations

  • Edit custom annotations

  • Delete custom annotations

  • Set dictionary properties

  • Add a custom dictionary property

  • Rename a custom dictionary property

  • Clear a dictionary property

  • Delete a custom dictionary property

  • Select codes

  • Clear codes

  • Clear a property for any field in the Value column

  • Automatically calculate field positions


Set document delimiters

  1. On the Tools menu, click Options.

    The BizTalk Editor Options dialog box appears.

  2. Click the Document Delimiters tab.

  3. Select an option from each of the following lists:
    • Record delimiter

    • Field delimiter

    • Subfield delimiter

    • Escape character

    Important

    • If you specify your own delimiters, use Unicode character values. For a list of valid characters, go to the Global codepages page on the Microsoft Global Software Development Web site (www.microsoft.com/globaldev/reference/wincp.asp). You can use ANSI character codes, provided they are the same as the Unicode character code except for having two leading zeros.
  4. If you want to display the Document Delimiters tab each time you validate a document instance so that you can specify unique document delimiters, click Prompt for delimiters during instance test.

Important

  • If you are prompted for delimiters during instance testing because the Prompt for delimiters during instance test box is checked, the delimiters you specify are used only to test that instance. The delimiters specified on the Document Delimiters tab remain the default delimiters.

  • Null terminator (delimiter) is not supported. Remove the null delimiter from the flat file.

Note

  • If the instance contains multiple documents and envelope information (header/trailer), only the first document will be validated against the document delimiters specified on the Document Delimiters tab.


Set declaration properties

  1. In the specification tree, click the root node, record, or field for which you want to set a property, and then click the Declaration tab.

  2. Double-click the field in the Value column that is associated with the property that you want to set.

  3. Type data in the field or click the down arrow to select from a list of available options.

  4. Press ENTER to accept your changes.

The Declaration tab contains the properties shown in the following tables. The properties that you select are set for the root node, a record, or a field, depending on which node you have selected.

Declaration Tab: Root Node Properties

Property | Value
Name The name of the root node.

Note

  • If you change the Name value on the Declaration tab, the name of the root node in the specification tree automatically changes to match it. In a newly created specification, changing the Name value on the Declaration tab also changes the Specification Name value on the Reference tab. However, since it is possible to have a specification name that is different from the root node name, changing the Specification Name value has no effect on the Name value or the root node name in the specification tree. Once the Specification Name value has been edited, however, changing the Name value or the root node name has no effect on the Specification Name value.
Description | The description of the specification.
Type | The type of record. This is always set to Element for the root node.
Model Closed. Indicates that the data contained in the document instance and the specification structure match.

Open. Indicates that the data in the document instance and the specification structure might not match.

Important

  • If you change the Content value from Text Only to Element Only, and change the Model value from Closed to Open, then the Dictionary tab property values will still be associated with the specification and the file will not successfully pass through the BizTalk Server engine.

Note

  • If this property value is left blank, the default value is Open.
Content Element Only. Indicates that the record can contain only elements. This is the automatic default for any record that contains a child record.

Mixed. Indicates that the root node can contain mixed content (text information as well as subelements). This is available only if the Standard value is XML.

Important

  • The root node can have a Content value only of Element Only or Mixed because it contains child records.

  • The element can contain a mix of named elements and text. Mixed is the default value. If the value of the content attribute is mixed, Minimum Occurrences and Maximum Occurrences attributes will not trigger a validation error if the number of child elements is outside the specified boundary.

  • If an element contains mixed content, for example data interspersed with child elements, and in BizTalk Mapper you select Copy text value (default), the only content that will be copied is the content that exists up to the first child element. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item being copied.

  • If an element contains mixed content, for example data interspersed with child elements, and in BizTalk Mapper you select Copy text and sub-content value, all the content, including the child elements, will be copied. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item1121314Number being copied.

Note

  • If you select Mixed, you must select Many for the Order property value.
Order If the Structure is XML, select one of the following values:
  • Many. Indicates that zero or more of the constituent elements can appear, in any order or combination.

  • One. Indicates that one and only one of the constituent elements can appear.

  • Sequence. Indicates that the constituent elements must appear in the order specified.

Note

  • If Many is selected, all the Minimum Occurrence and Maximum Occurrence values for the child records will be ignored.

Declaration Tab: Record Properties

Property | Value
Name | The name of the record.
Description | The description of the record.
Type | The type of record.
Data Type A valid data type. For a list and description of all valid data types, see Summary of Data Type and Data Type Values.

Important

  • If the Content type property is Text Only, you can specify a Data Type property.
Data Type Values If you select Enumeration in the Data Type list, the data type values a b c appear by default in the Data Type Values box. You can replace the default values with custom values separated by spaces.

If you are working with an X12 or EDIFACT document and include codes associated with a particular field, those codes automatically appear in the Data Type Values box, and Enumeration automatically appears in the Data Type box.

Important

  • If the Content type property is Text Only, you can specify a Data Type Value property.

  • You cannot use the number sign (#), ampersand (&), or colon (:) characters as Data Type Values.
Model Closed. Indicates that the data contained in the document instance and the specification structure match.

Open. Indicates that the data in the document instance and the specification structure might not match.

Important

  • If you change the Content value from Text Only to Element Only, and change the Model value from Closed to Open, then the Dictionary tab property values will still be associated with the specification and the file will not successfully pass through the BizTalk Server engine.

Note

  • If this property value is left blank, the default value is Open.
Content Element Only. Indicates that the record can contain only elements. This is the automatic default for any record that contains a child record.

Empty. Indicates that the record cannot contain subelements.

Text Only. Indicates that the record can contain text, but not subelements.

Mixed. Indicates that the root node can contain mixed content (text information as well as subelements).

Important

  • Records with child records can have a Content value only of Element Only or Mixed. If a record does not have child records, Empty and Text Only are also available in the list.

  • The element can contain a mix of named elements and text. Mixed is the default value. If the value of the content attribute is mixed, Minimum Occurrences and Maximum Occurrences attributes will not trigger a validation error if the number of child elements is outside the specified boundary.

  • If you change the Content value from Text Only to Element Only, and change the Model value from Closed to Open, then the Dictionary tab property values will still be associated with the specification and the file will not successfully pass through the BizTalk Server engine.

  • If an element contains mixed content, for example data interspersed with child elements, and in BizTalk Mapper you select Copy text value (default), the only content that will be copied is the content that exists up to the first child element. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item being copied.

  • If an element contains mixed content, for example data interspersed with child elements, and in BizTalk Mapper you select Copy text and sub-content value, all the content, including the child elements, will be copied. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item1121314Number being copied.

Notes

  • If you select Text Only, you can specify the Data Type and Data Type Value properties.

  • If you select Mixed, you must select Many for the Order property value.
Order If the Structure is XML, select one of the following values:
  • Many. Indicates that zero or more of the constituent elements can appear, in any order or combination.

  • One. Indicates that one and only one of the constituent elements can appear.

  • Sequence. Indicates that the constituent elements must appear in the order specified.

Note

  • If Many is selected, all the Minimum Occurrence and Maximum Occurrence values for the child records will be ignored.
Cycle Count Type the number of cycles you want to be available below the base record. For more information, see Cyclical References.

Note

  • This property field appears only if you have created a cyclical reference. The default value is 7.

Declaration Tab: Field Properties

Property | Value
Name | The name of the field.
Description | The description of the field.
Type Select one of the following values:
  • Element

  • Attribute

Note

  • If the structure of your specification is positional, it is not recommended that you specify Element as the Type value. Doing so may cause validation to fail.
Model Closed. Indicates that the data contained in the document instance and the specification structure match.

Open. Indicates that the data in the document instance and the specification structure might not match.

Notes

  • If this property value is left blank, the default value is Open.

  • The Model property is available only for a field with its Type value set to Element.
Content Text Only. Indicates that the field can contain text and not subelements.

Notes

  • The Content property is available only for a field with its Type value set to Element.

  • Text Only is the only value available for the Content property of a field.
Data Type A valid data type. For a list and description of all valid data types, see Summary of Data Type and Data Type Values.

Important

  • If the Standard property value on the Reference tab is set to X12, EDIFACT, or CUSTOM, you can assign a Custom Data Type value on the Parse tab. If you specify a Custom Data Type value, the Data Type value is automatically changed to match the selection that you specified for the Custom Data Type value.

  • In a specification, if you create a field with the Data Type property set to IDREF or IDREFS, you must create another field in that specification with the Data Type set to ID.

  • To select a field for tracking or for use in a channel filtering expression in BizTalk Messaging Manager, you must assign a data type to that field in the specification.
Data Type Values If you select Enumeration in the Data Type list, the data type values a b c appear by default in the Data Type Values box. You can replace the default values with custom values separated by spaces.

If you are working with an X12 or EDIFACT document and include codes associated with a particular field, those codes automatically appear in the Data Type Values box, and Enumeration automatically appears in the Data Type box.

Important

  • You cannot use the number sign (#) or ampersand (&) characters as Data Type Values.
Minimum Length The minimum number of characters that the field can contain.

Notes

  • The Minimum Length property can be set only for fields with the following Data Type values: String, Number, Binary (base64), and Binary (hex).

  • If implied decimal is specified for the Custom Data Type property, it is not recommended that you specify a Minimum Length value. If you must specify a Minimum Length value, the value should be less than Nx, where x represents a number between 1 and 9. The Nx value is available on the Custom Data Type property list.
Maximum Length The maximum number of characters that the field can contain.

Note

  • The Maximum Length property can be set only for fields with the following Data Type values: String, Number, Binary (base64), and Binary (hex).
Default Value Type a numeric value. For more information, see Default Value Integration.

Notes

  • The Default Value property appears in specifications only when the Standard property (on the Reference tab for the root node) is set to XML, and the Type property (on the Declaration tab for the field) is set to Attribute.

  • You cannot use the following characters:
    • Accent grave (`)

    • Apostrophe (')

    • Asterisk (*)

    • Backslash (\)

    • Braces ({ })

    • Brackets ([ ])

    • Caret (^)

    • Colon (:)

    • Comma (,)

    • Dollar sign ($)

    • Equal sign (=)

    • Exclamation point (!)

    • Percent (%)

    • Period (.)

    • Pipe (|)

    • Plus (+)

    • Question mark (?)

    • Semi-colon (;)

    • Slash (/)

    • Tilde (~)

Related Topics

Add channel filtering expressions

Character Length Limits

Cyclical References

Default Value Integration

Select specification fields in a channel

Select specification fields in a document definition

Summary of Data Type and Data Type Values


Set reference properties

  1. In the specification tree, click the root node, record, or field for which you want to set a property, and then click the Reference tab.

  2. Double-click the field in the Value column that is associated with the property that you want to set.

  3. Type data in the Value column field or click the down arrow to select from a list of available options.

The Reference tab contains the properties described in the following tables. The properties that you select are set for the root node, a record, or a field, depending on which node you have selected.

Reference Tab: Root Node Properties

Property | Value
Specification Name | The name of the specification. This name corresponds to the value of the <Schema> tag in the specification.
Standard Select one of the following values:
  • XML for creating a specification based on Extensible Markup Language (XML).

  • X12 for creating a specification based on X12.

  • EDIFACT for creating a specification based on EDIFACT.

  • CUSTOM for creating a specification based on a flat file, or for creating a custom specification to be parsed with a custom parser.

Important

  • If you change the Standard property value from X12 to CUSTOM (for example, for flat files), and then select a field and set the Custom Data Type value on the Parse tab to Number (N) or Number (Nx), where x represents a number between 1 and 9, the Custom Maximum Length property on the Parse tab for the field will not display. Therefore, you will need to increase the Maximum Length value on the Declaration tab to accommodate the resulting parsed or serialized output when a specification is going from or going to an implied decimal format.
Standards Version | The standards version, such as X12 version 4010, on which the specification is based.
Document Type | The document type, such as 850, on which the specification is based.
Version | The version number of the document standard on which the specification is based.
Default Record Delimiter Type or select a character to be used as the delimiter within any node for which the Delimiter Type property on the Parse tab is set to Default Record Delimiter.

Note

  • This property field displays only if the Standard field on the Reference tab (for the root node) is set to CUSTOM.
Default Field Delimiter Type or select a character to be used as the delimiter within any node for which the Delimiter Type property on the Parse tab is set to Default Field Delimiter.

Important

  • Repeating field-level delimiters, which are typically in ANSI X12 version 4030 and later, are not supported.

Note

  • This property field displays only if the Standard field on the Reference tab (for the root node) is set to CUSTOM.
Default Subfield Delimiter Type or select a character that will be used as the delimiter within any node for which the Delimiter Type property on the Parse tab is set to Default Subfield Delimiter.

Note

  • This property field displays only if the Standard field on the Reference tab (for the root node) is set to CUSTOM.
Default Escape Character Type or select a character that will be used as the escape character within any node for which the Escape Type property on the Parse tab is set to Default Escape Character.

Note

  • This property field displays only if the Standard field on the Reference tab (for the root node) is set to CUSTOM.
Code Page Choose one of the following values:
  • Arabic (1256)

  • Baltic (1257)

  • Central-European (1250)

  • Cyrillic (1251)

  • Greek (1253)

  • Hebrew (1255)

  • Japanese-Shift-JIS (932)

  • Korean (949)

  • Little-Endian-UTF16 (1200)

  • Simplified-Chinese-GBK (936)

  • Thai (874)

  • Traditional-Chinese-Big5 (950)

  • Turkish (1254)

  • Vietnamese (1258)

  • Western-European (1252)

Notes

  • This property field displays only if the Standard field on the Reference tab (for the root node) is set to CUSTOM.

  • UTF7 (65000) and UTF8 (65001) are not supported by BizTalk Server.

  • If the Code Page value is left blank, the default value is Western-European (1252).
Receipt Choose one of the following options:
  • Yes. Indicates that the specification is to be used as an inbound receipt document. A correlator component (X12, EDIFACT, or CUSTOM) is expected to correlate the receipt document to the outbound document that it acknowledges (in other words, something previously sent to the sender of the receipt).

  • No. Indicates that the specification is not to be used as an inbound receipt document.

Notes

  • If the receipt value is left blank, the default value is No.

  • For specifications based on the CanonicalReceipt and for specifications to which the CanonicalReceipt is mapped (both are used in the scenario of generating an outbound receipt), the Receipt property should be set to No.
Envelope Choose one of the following options:
  • Yes. Indicates that the specification is an interchange specification.

  • No. Indicates that the specification is not an interchange specification.

Notes

  • This property is used only for flat files and XML files for envelopes.

  • If the field is left blank, it assumes the value of No.
Target Namespace If you have a BizTalk Framework instance and have specified a namespace in the instance, you must enter the corresponding namespace used in the instance.

Note

  • If you use "x-schema" in the target namespace value of an instance, you might cause a test failure when you test the instance in BizTalk Mapper.

Reference Tab: Record Properties

Property Value
Minimum Occurrences The minimum number of times a record can occur in its position within the node hierarchy. Possible values are 0 or 1.

Note

  • If this property value is left blank, the default value is 1.
Maximum Occurrences The maximum number of times a record can occur in its position within the node hierarchy. Possible values are 1 and asterisk (*).

Notes

  • If you type an asterisk (*), the record is considered to be a looping record. If this specification is used in BizTalk Mapper, it compiles this record as a loop. If you type 1, BizTalk Mapper does not consider this record to be a looping record.

  • If this property value is left blank, the default value is 1.

Reference Tab: Field Properties

Property Value
Required Choose one of the following options:
  • Yes. Indicates that the field is required.

  • No. Indicates that the field is not required.

Note

  • If this property value is left blank, the default value is No.
Start Position A number that indicates the starting position of the field in the record.

Note

  • This property field displays only if the structure of the parent record is positional.
End Position A number that indicates the ending position of the field in the record.

Note

  • This property field displays only if the structure of the parent record is positional.

Related Topics

Calculating Field Positions

Character Length Limits

Understanding Receipts


Set parse properties

  1. In the specification tree, click the root node, record, or field for which you want to set a property, and then click the Parse tab.

  2. Double-click the field in the Value column that is associated with the property that you want to set.

  3. Type data in the field or click the down arrow to select from a list of available options.

The Parse tab contains the properties described in the following tables. The available properties depend on the standard (X12, EDIFACT, or CUSTOM) and on the structure property that you use. By default, new specifications based on a blank specification have a standard property of Extensible Markup Language (XML). For each property, enter a value as needed. The properties that you select are set for the root node, a record, or a field, depending on which node you have selected.

Standard: XML

Parse Tab: Root Node, Record, and Field Properties

These properties do not display.

Standard: X12 or EDIFACT

Important

  • The Wrap, Pad, Escape, and Delimiter values for a record and its child fields should be mutually exclusive.

Parse Tab: Root Node or Record Properties

Property Value
Structure This value automatically defaults to Delimited for the root node.

Note

  • If the Standard property value is set to X12 or EDIFACT on the Reference tab for the root node of a specification, you cannot edit the Structure property value on the Parse tab for the root node or any record. If you want to edit the Structure property value, you must change the standard to CUSTOM.
Source Tag Identifier The name of the source tag identifier. This is the tag name that is used to match the record with the data.

Important

  • If you have a loop record and the instance data does not contain a loop structure (meaning the structure is implied rather than explicit), make sure the Source Tag Identifier value is blank.

Notes

  • For a non-XML file such as a flat file, you can type a Source Tag Identifier property to identify any tag that might exist in the original file. A Source Tag Identifier cannot contain the following characters: < > " &

  • The Source Tag Identifier property is case sensitive.
Field Order Select one of the following options:
  • Prefix. A prefix delimiter appears before each component, and each member of a component in a series. For example, where an asterisk (*) is the delimiter: *a*a*b*c.

  • Postfix. A postfix delimiter appears after each component, and each member or a component in a series. For example, where * is the delimiter: a*a*b*c*.

  • Infix. An infix delimiter appears between components, and members of components in a series. For example, where * is the delimiter: a*a*b*c.

Notes

  • For most common cases of non-XML files, the root node Field Order should be set to Postfix and loop record nodes should be set to Infix. For examples of how this applies, see samples in both the Flat-FileDelimited and Flat-FilePositional folders located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\.

  • If the Field Order value is left blank, the default value is Prefix.
Delimiter Type Select one of the following options to choose a delimiter for the child nodes directly below the current node:
  • Default Record Delimiter. Indicates that the delimiter is the value of the Default Record Delimiter property, which is defined in the document instance.

  • Default Field Delimiter. Indicates that the delimiter is the value of the Default Field Delimiter property, which is defined in the document instance.

  • Default Subfield Delimiter. Indicates that the delimiter is the value of the Default Subfield Delimiter property, which is defined in the document instance.
Escape Type

(Also known as a release character)

 Select the following option to indicate that you want an escape character for the child nodes directly below the current node:
  • Default Escape Character. Indicates that the escape character is a value defined in the document instance.

An escape character is useful if you have a character in your field data that is also used as the delimiter character for the field's parent node. For example, if your field data is the following and you have chosen a comma as the delimiter value of the node that contains the field, BizTalk Editor interprets the comma after "Browne" to be a delimiter, even if you intend for it to be part of the field data:

Brown,Robert,1231,yes

A solution for this is to place an escape character directly preceding the delimiter character that you want to include in the field data. For example, if your escape character is specified as a backslash, you can place a backslash directly preceding a delimiter character, as in the following example:

Brown\,Robert,1231,yes

BizTalk Editor interprets the comma after the backslash as field data rather than a delimiter character.

Note

  • The Escape Type property is not available for X12 specifications.
Append Newline Select one of the following options:
  • Yes. Indicates that when the serializer reaches the record delimiter, the serializer automatically appends a new line (LF,0x0A).

  • No. Indicates that when the serializer reaches the record delimiter, the serializer continues on the same line for the following record.

Note

  • If the Append Newline value is left blank, the default value is No.
Skip Carriage Return Select one of the following options:
  • Yes. Tells the parser to skip the carriage return (CR) value after a delimiter.

  • No. Tells the parser not to skip the CR value after a delimiter.

Note

  • If the Skip Carriage Return value is left blank, the default value is Yes.
Skip Line Feed Select one of the following options:
  • Yes. Tells the parser to skip the line feed (LF) value after a delimiter.

  • No. Tells the parser not to skip the LF value after a delimiter.

Note

  • If the Skip Line Feed value is left blank, the default value is Yes.
Ignore Record Count Select one of the following options:
  • Yes. Tells the parser or the serializer not to count this record when counting the total number of records in the specification.

  • No. Tells the parser or the serializer to count this record when counting the total number of records in the specification.

Notes

  • When a document instance is submitted to BizTalk Server, if the number of records in the document instance does not match the calculated number of records in the specification, a parsing failure results. For more information, see Parsing errors.

  • If the Ignore Record Count value is left blank, the default value is Yes.
Trigger Field Select an option from the list. The options reflect the available trigger fields.

Important

  • This property is available only if Standard is set to X12.

Note

  • For more information about trigger fields, see General Purpose Triggers.
Trigger Value This value represents the data type value for the trigger field.

Important

  • This property is available only if Standard is set to X12.

Note

  • If you are using Microsoft® BizTalk™ Accelerator for HIPAA schema, do not change the values for the trigger properties.
SubDocument Creation Break Select one of the following options:
  • Yes. Tells the parser or serializer to create a new instance that replicates all the parent hierarchy above the record.

  • No. Tells the parser or serializer not to create a new instance that replicates all the parent hierarchy above the record.

Important

  • This property will only appear if the schema contains it.

  • This property is only available if Standard is set to X12.

Note

  • If you do not specify Yes, the SubDocument Creation Break property value will default to No and will tell the parser or serializer not to create a new instance that replicates all the parent hierarchy above the record.

Parse Tab: Field Properties

Property | Value
Custom Data Type Select one of the following options:
  • String (AN). AN is for alphanumeric fields.

  • Binary Hexadecimal (B). B is for binary fields.

  • Date (CY). CY is for four-digit date fields.

  • Number (D0-D4). D0 through D4 (inclusive) are for decimal fields. The single-digit number represents the number of digits to the right of the decimal.

  • Date (DT). DT is for date fields.

  • String (ID). ID is for identification fields.

  • Number (N). N is for integer fields.

  • Number (N1-9). N1 through N9 (inclusive) are for implied decimal fields (the decimal character does not appear in the data). The single-digit number represents the number of digits to the right of the decimal.

    Notes

    • When a specification is going from or going to an implied decimal format, you need to make sure the Custom Maximum Length value can handle the resulting parsed or serialized output. For example, if the Custom Data Type value is set to N2, then the Custom Maximum Length must be at least 3. This is necessary because the parser will insert the decimal during parsing, and the serializer will remove it, and also validate the number-right-of-decimal count.

    • If you change the Standard property value from X12 to CUSTOM (for example, for flat files) on the Reference tab, and then select Number (N) or Number (Nx), where x represents a number between 1 and 9, the Custom Maximum Length property will not display. Therefore, you will need to increase the Maximum Length value on the Declaration tab to accommodate the resulting parsed or serialized output when a specification is going from or going to an implied decimal format.
  • Number (R). R is for real number fields.

  • Time (TM). TM is for time fields.

Important

  • If you specify a Custom Data Type value, the Data Type value on the Declaration tab is automatically changed to match the selection that you specified for the Custom Data Type value. For example, if you change the Custom Data Type value on the Parse tab to Date (CY), the Data Type value on the Declaration tab automatically changes to Date.

Notes

  • If you specify Date (DT), Date (CY), or Time (TM) for the Custom Data Type property, you must also set a value for the Custom Date/Time Format property.

  • All of these custom data type values are supported in specifications with the Standard property set to X12. For specifications with the Standard property set to EDIFACT, the supported custom data type values are String (AN) and Number (N).
Custom Date/Time Format If you set Date (DT), Date (CY), or Time (TM) as the Custom Data Type property, click an option in the list. For more information, see Apply the Custom Date/Time Format property. For information about supported time formats, see Supported Time Format for X12.

Note

  • This property field is available only if the Custom Data Type is set to Date (DT), Date (CY), or Time (TM).

Important

  • Parsers in BizTalk Server do not recognize the Julian date format in an incoming document instance. A Julian date format includes three digits that indicate the day (DDD). Although it is possible to create specifications in BizTalk Editor that use the Julian date format, this capability is provided for use only with custom parsers that can recognize document instances using the Julian date format. Do not use the Julian date format in a specification or a document instance unless you are employing a custom parser that recognizes the Julian date format.
Justification Select one of the following options:
  • Left. Aligns data to the left in positional flat files when the data is less than the maximum field length. Also aligns data to the left in delimited flat files when the amount of data is less than the minimum length requirement.

  • Right. Aligns data to the right in positional flat files when the data is less than the maximum field length. Also aligns data to the left in delimited flat files when the amount of data is less than the minimum length requirement.

Note

  • If the Justification value is left blank, the default value is Left.
Pad Character | Type a character to pad the field. You can choose any character for a pad character, including a space or a zero. For more information, see Pad Characters.
Wrap Character Type a character to enclose field data. This property is useful if you have a character in your field data that is also used as the delimiter value for the field's parent node. For example, if your field data is the following and you have chosen a comma as the delimiter value of the node that contains the field, BizTalk Editor interprets the comma after "Browne" to be a delimiter, even if you intend for it to be part of the field data:

Brown,Robert,1231,yes

A solution for this is to define a value for the wrap character property and then enclose the field data in the wrap character. For example, you can set the wrap character property to double quotation marks for the first field and then type your field data, as in the following example:

"Brown,Robert",1231,yes

The comma between the double quotation marks is interpreted by BizTalk Editor to be field data rather than a delimiter value.

Important

  • If you have a field that uses a wrap character, there cannot be any data between the wrap character and any delimiter leading or following a wrap character.

Notes

  • If your field data includes characters that are also used as the wrap character, you must enclose those characters in another set of wrap characters.

    For example, if the wrap character value is set to double quotation marks, as in the following:

    "Brown,Robert ""Rob"""

    BizTalk Editor will parse it to appear as:

    Brown,Robert "Rob"
Minimum Length with Pad Character The minimum length of a field in an output document instance, including pad characters. For more information about pad characters, see Pad Characters.

Notes

  • This property can be set only if the pad character is set for that field.

  • If the Minimum Length property on the Declaration tab is set for the field, the Minimum Length with Pad Character property must be greater than or equal to the value of the Minimum Length property. If the Minimum Length property is not set, the Minimum Length with Pad Character property must be greater than or equal to 1.
Custom Maximum Length Enter a number that represents the maximum number of characters that this field can have and press ENTER.

Notes

  • This property enables you to use periods, dashes, and so forth in your numbers field.

  • This property appears only if the Custom Data Type value is Number (N), Number (Nx), or Number (R), where x equals a number between 1 and 9.

  • The Custom Maximum Length value must be greater than x (where x equals a number between 1 and 9 in the Nx) for an EDI instance. For example, if the Custom Data Type value is set to N2, then the Custom Maximum Length must be at least 3. This is necessary because the parser will insert the decimal during parsing, and the serializer will remove it, and also validate the number-right-of-decimal count.

Standard: Custom
Structure Property: Delimited

Important

  • The Wrap, Pad, Escape, and Delimiter values for a record and its child fields should be mutually exclusive.

  • It is highly recommended that you ensure that the wrap character is different from the escape character.

Parse Tab: Root Node or Record Properties

Property | Value
Structure Select the following option for the Root Node property:
  • Delimited. Indicates that the root node is based on a delimited file structure. Records can be individually based on delimited or positional file structures.

Select one of the following options for Record properties:

  • Delimited. Indicates that the record is based on a delimited file structure. Descendant records can be individually based on delimited or positional file structures.

  • Positional. Indicates that the record is based on a positional file structure. Positional records cannot have child records.

Notes

  • For a document to be both delimited and positional, the root node must have its Structure property set to Delimited. You can then set the Structure property for individual records to Positional or Delimited, as necessary.

  • If the structure of your specification is positional, it is not recommended that you specify Element as the Type value on the Declaration tab for fields. Doing so may cause validation to fail.

  • If you change from one structure to another, a message box appears. Click Yes to confirm the structure change. Some new properties might appear, and some existing properties might be removed.

  • If you right-click the Structure property value field of a positional record and click Clear Property, BizTalk Editor interprets the structure of the record as delimited. Some new properties might appear, and some existing properties might be removed.

  • When the Standard property for a new document is set to CUSTOM, by default the Structure property for the root node and all records is blank. If you leave the Structure property blank, its value is Delimited.
Source Tag Identifier The name of the source tag identifier. This is the tag name that is used to match the record with the data.

Important

  • If you have a loop record and the instance data does not contain a loop structure (meaning the structure is implied rather than explicit), make sure the Source Tag Identifier value is blank.

Notes

  • For a non-XML file, such as a flat file, you can type a Source Tag Identifier property to identify any tag that might exist in the original file. A Source Tag Identifier cannot contain the following characters: < > " &

  • The Source Tag Identifier property is case sensitive.
Field Order Select one of the following options:
  • Prefix. A prefix delimiter appears before each component, and each member of a component, in a series. For example, where an asterisk (*) is the delimiter: *a*a*b*c.

  • Postfix. A postfix delimiter appears after each component, and each member of a component, in a series. For example, where * is the delimiter: a*a*b*c*.

  • Infix. An infix delimiter appears between components, and members of components, in a series. For example, where * is the delimiter: a*a*b*c.

Notes

  • For most common cases of non-XML files, the root node Field Order should be set to Postfix and loop record nodes should be set to Infix. For examples of how this applies, see samples in both the Flat-FileDelimited and Flat-FilePositional folders located at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\.

  • If the field order value is left blank, the default value is Prefix.
Delimiter Type Select one of the following options to choose a delimiter for the child nodes directly below the current node:
  • Character. Allows you to designate a delimiter value on the Parse tab. If you select Character, you must specify a delimiter value.

  • Default Record Delimiter. Indicates that the delimiter is the value of the Default Record Delimiter property, on the Reference tab for the root node.

  • Default Field Delimiter. Indicates that the delimiter is the value of the Default Field Delimiter property, on the Reference tab for the root node.

  • Default Subfield Delimiter. Indicates that the delimiter is the value of the Default Subfield Delimiter property, on the Reference tab for the root node.
Delimiter Value | Type or select a character value for the delimiter. To specify a delimiter value, you must first set the Delimiter Type to Character on the Parse tab.
Escape Type

(Also known as a release character)

 Select one of the following options to choose an escape character for the child nodes directly below the current node:
  • Character. Allows you to designate an escape character value on the Parse tab. If you select Character, you must specify an escape value.

  • Default Escape Character. Indicates that the escape character is the value of the Default Escape Character property, on the Reference tab for the root node.

An escape character is useful if you have a character in your field data that is also used as the delimiter character for the field's parent node. For example, if your field data is the following and you have chosen a comma as the delimiter value of the node that contains the field, BizTalk Editor interprets the comma after "Browne" to be a delimiter, even if you intend for it to be part of the field data:

Brown,Robert,1231,yes

A solution for this is to place an escape character directly preceding the delimiter character that you want to include in the field data. For example, if your escape character is specified as a backslash, you can place a backslash directly preceding a delimiter character, as in the following example:

Brown\,Robert,1231,yes

BizTalk Editor interprets the comma after the backslash as field data rather than a delimiter character.
Escape Value | Type or select a character value for the escape character. To specify an escape character value, you must first set the Escape Type to Character on the Parse tab.
Append Newline Select one of the following options:
  • Yes. Indicates that when the serializer reaches the record delimiter, the serializer automatically appends a new line (LF,0x0A).

  • No. Indicates that when the serializer reaches the record delimiter, the serializer continues on the same line for the following record.

Note

  • If the Append Newline value is left blank, the default value is No.
Skip Carriage Return Select one of the following options:
  • Yes. Tells the parser to skip the carriage return (CR) value after a delimiter.

  • No. Tells the parser not to skip the CR value after a delimiter.

Note

  • If the Skip Carriage Return value is left blank, the default value is Yes.
Skip Line Feed Select one of the following options:
  • Yes. Tells the parser to skip the line feed (LF) value after a delimiter.

  • No. Tells the parser not to skip the LF value after a delimiter.

Note

  • If the Skip Line Feed value is left blank, the default value is Yes.
Ignore Record Count Select one of the following options:
  • Yes. Tells the parser or the serializer not to count this record when counting the total number of records in the specification.

  • No. Tells the parser or the serializer to count this record when counting the total number of records in the specification.

Notes

  • When a document instance is submitted to BizTalk Server, if the number of records in the document instance does not match the calculated number of records in the specification, a parsing failure results. For more information, see Parsing errors.

  • If the Ignore Record Count value is left blank, the default value is Yes.

Parse Tab: Field Properties

Property | Value
Custom Data Type Select one of the following options:
  • String (AN). AN is for alphanumeric fields.

  • Binary Hexadecimal (B). B is for binary fields.

  • Date (CY). CY is for four-digit date fields.

  • Number (D0-D4). D0 through D4 (inclusive) are for decimal fields. The single-digit number represents the number of digits to the right of the decimal.

  • Date (DT). DT is for date fields.

  • String (ID). ID is for identification fields.

  • Number (N). N is for integer fields.

  • Number (N1-9). N1 through N9 (inclusive) are for implied decimal fields (the decimal character does not appear in the data). The single-digit number represents the number of digits to the right of the decimal.

    Notes

    • When a specification is going from or going to an implied decimal format, you need to make sure the Custom Maximum Length value can handle the resulting parsed or serialized output. For example, if the Custom Data Type value is set to N2, then the Custom Maximum Length must be at least 3. This is necessary because the parser will insert the decimal during parsing, and the serializer will remove it, and also validate the number-right-of-decimal count.

    • If you change the Standard property value from X12 to CUSTOM (for example, for flat files) on the Reference tab, and then select Number (N) or Number (Nx), where x represents a number between 1 and 9, the Custom Maximum Length property will not display. Therefore, you will need to increase the Maximum Length value on the Declaration tab to accommodate the resulting parsed or serialized output when a specification is going from or going to an implied decimal format.
  • Number (R). R is for real number fields.

  • Time (TM). TM is for time fields.

Important

  • If you specify a Custom Data Type value, the Data Type value on the Declaration tab is automatically changed to match the selection that you specified for the Custom Data Type value. For example, if you change the Custom Data Type value on the Parse tab to Date (CY), the Data Type value on the Declaration tab automatically changes to Date.

Note

  • If you specify Date (DT), Date (CY), or Time (TM) for the Custom Data Type property, you must also set a value for the Custom Date/Time Format property.
Custom Date/Time Format If you set Date (DT), Date (CY), or Time (TM) as the Custom Data Type property, click an option in the list. For more information, see Apply the Custom Date/Time Format property. For information about supported time formats, see Supported Time Format for X12.

Note

  • This property field is available only if the Custom Data Type is set to Date (DT), Date (CY), or Time (TM).
Justification Select one of the following options:
  • Left. Aligns data to the left in positional files when the data is less than the maximum field length. This also aligns data to the left in delimited files when the amount of data is less than the minimum length requirement.

  • Right. Aligns data to the right in positional flat files when the data is less than the maximum field length. Also aligns data to the left in delimited flat files when the amount of data is less than the minimum length requirement.

Note

  • If the Justification value is left blank, the default value is Left.
Pad Character | Type or select a character to pad the field. You can choose any character for a pad character, including a space or a zero. For more information, see Pad Characters.
Wrap Character Type a character to enclose field data. This property is useful if you have a character in your field data that is also used as the delimiter value for the field's parent node. For example, if your field data is the following and you have chosen a comma as the delimiter value of the node that contains the field, BizTalk Editor interprets the comma after "Browne" to be a delimiter, even if you intend for it to be part of the field data:

Brown,Robert,1231,yes

The solution to this is to define a value for the wrap character property and then enclose the field data in the wrap character. For example, you can set the wrap character property to double quotation marks for the first field and then type your field data, as in the following example:

"Brown,Robert",1231,yes

The comma between the double quotation marks is interpreted by BizTalk Editor to be field data rather than a delimiter value.

Notes

  • If you have characters in your field data that are also used as the wrap character, you must enclose those characters in another set of wrap characters.

    For example, if the wrap character value is set to double quotation marks, as in the following:

    "Brown,Robert ""Rob"""

    BizTalk Editor will parse it to appear as:

    Brown,Robert "Rob"

  • If the field data in an input document instance includes the line feed character followed directly by the carriage return character, the corresponding field data in the output document instance includes only the line feed character, even if both are enclosed in a set of wrap characters.
Minimum Length with Pad Character The minimum length of a field in an output document instance, including pad characters. For more information, see Pad Characters.

Notes

  • This property can be set for a field only if the pad character is set for that field.

  • If the Minimum Length property on the Declaration tab is set for the field, the Minimum Length with Pad Character property must be greater than or equal to the value of the Minimum Length property. If the Minimum Length property is not set, the Minimum Length with Pad Character property must be greater than or equal to one.

Standard: Custom
Structure Property: Positional

Parse Tab: Root Node Properties or Record Properties

Property | Value
Structure Select the following option for the Root Node property:
  • Positional. Indicates that the root node is based on a positional flat file structure.

Important

  • The recommended maximum size limit for a field is 1 megabyte (MB). You can exceed this limit; however, performance of BizTalk Server will be greatly reduced.

Notes

  • If the structure of your specification is positional, it is not recommended that you specify Element as the Type value on the Declaration tab for fields. Doing so may cause validation to fail.

  • A document with a positional root node cannot have records.

  • If you right-click the Structure property value field of a positional root node and click Clear Property, BizTalk Editor interprets the structure of the root node as delimited. Some new properties might appear, and some existing properties might be removed.

  • When the Standard property for a new document is set to CUSTOM, by default the Structure property for the root node and all records is blank. If you leave the Structure property blank, its value is Delimited.
Source Tag Identifier The name of the source tag identifier. This is the tag name that is used to match the record with the data.

Important

  • If you have a loop record and the instance data does not contain a loop structure (meaning the structure is implied rather than explicit), make sure the Source Tag Identifier value is blank.

Notes

  • For a non-XML file, such as a flat file, you can type a Source Tag Identifier property to identify any tag that might exist in the original file. A Source Tag Identifier cannot contain the following characters: < > " &

  • The Source Tag Identifier property is case sensitive.
Source Tag Position | A number that refers to the position of the beginning of the tag in a positional record.
Append Newline Select one of the following options:
  • Yes. Indicates that when the serializer reaches the record delimiter, the serializer automatically appends a new line (LF,0x0A).

  • No. Indicates that when the serializer reaches the record delimiter, the serializer continues on the same line for the following record.

Note

  • If the Append Newline value is left blank, the default value is No.
Skip Carriage Return Select one of the following options:
  • Yes. Tells the parser to skip the carriage return (CR) value after a delimiter.

  • No. Tells the parser not to skip the CR value after a delimiter.

Note

  • If the Skip Carriage Return value is left blank, the default value is Yes.
Skip Line Feed Select one of the following options:
  • Yes. Tells the parser to skip the line feed (LF) value after a delimiter.

  • No. Tells the parser not to skip the LF value after a delimiter.

Note

  • If the Skip Line Feed value is left blank, the default value is Yes.
Ignore Record Count Select one of the following options:
  • Yes. Tells the parser or the serializer not to count this record when counting the total number of records in the specification.

  • No. Tells the parser or the serializer to count this record when counting the total number of records in the specification.

Notes

  • When a document instance is submitted to BizTalk Server, if the number of records in the document instance does not match the calculated number of records in the specification, a parsing failure results. For more information, see Parsing errors.

  • If the Ignore Record Count value is left blank, the default value is Yes.

Parse Tab: Field Properties

Property | Value
Custom Data Type Select one of the following options:
  • String (AN). AN is for alphanumeric fields.

  • Binary Hexadecimal (B). B is for binary fields.

  • Date (CY). CY is for four-digit date fields.

  • Number (D0-D4). D0 through D4 (inclusive) are for decimal fields. The single-digit number represents the number of digits to the right of the decimal.

  • Date (DT). DT is for date fields.

  • String (ID). ID is for identification fields.

  • Number (N). N is for integer fields.

  • Number (N1-9). N1 through N9 (inclusive) are for implied decimal fields (the decimal character does not appear in the data). The single-digit number represents the number of digits to the right of the decimal.

    Notes

    • When a specification is going from or going to an implied decimal format, you need to make sure the Custom Maximum Length value can handle the resulting parsed or serialized output. For example, if the Custom Data Type value is set to N2, then the Custom Maximum Length must be at least 3. This is necessary because the parser will insert the decimal during parsing, and the serializer will remove it, and also validate the number-right-of-decimal count.

    • If you change the Standard property value from X12 to CUSTOM (for example, for flat files) on the Reference tab, and then select Number (N) or Number (Nx), where x represents a number between 1 and 9, the Custom Maximum Length property will not display. Therefore, you will need to increase the Maximum Length value on the Declaration tab to accommodate the resulting parsed or serialized output when a specification is going from or going to an implied decimal format.
  • Number (R). R is for real number fields.

  • Time (TM). TM is for time fields.

Important

  • If you specify a Custom Data Type value, the Data Type value on the Declaration tab is automatically changed to match the selection that you specified for the Custom Data Type value. For example, if you change the Custom Data Type value on the Parse tab to Date (CY), the Data Type value on the Declaration tab automatically changes to Date. If you specify a Data Type value on the Declaration tab, the Custom Data Type value is cleared.

Note

  • If you specify Date (DT), Date (CY), or Time (TM) for the Custom Data Type property, you must also set a value for the Custom Date/Time Format property.
Custom Date/Time Format If you set Date (DT), Date (CY), or Time (TM) as the Custom Data Type property, click an option in the list. For more information, see Apply the Custom Date/Time Format property. For information about supported time formats, see Supported Time Format for X12.

Note

  • This property field is active only if the Custom Data Type is set to Date (DT), Date (CY), or Time (TM).
Justification Select one of the following options:
  • Left. Aligns data to the left in positional flat files when the data is less than the maximum field length. Also aligns data to the left in delimited flat files when the amount of data is less than the minimum length requirement.

  • Right. Aligns data to the right in positional flat files when the data is less than the maximum field length. Also aligns data to the left in delimited flat files when the amount of data is less than the minimum length requirement.

Note

  • If the Justification value is left blank, the default value is Left.
Pad Character | Type a character to be used to pad the field. You can choose any character for a pad character, including a space or a zero. For more information, see Pad Characters.

Related Topics

Character Length Limits

Pad Characters


Apply the Custom Date/Time Format property

The Custom Date/Time Format data type enables you to send date and time information in the following format: HHMMSSDD. For more information about this time format, see the previous "Supported time format for X12" topic.

  1. In the specification tree, click the root node, record, or field for which you want to set the custom date/time property, and then click the Parse tab.

  2. Double-click the Value column next to Custom Data Type.

  3. Click Time (TM) from the list of options and press ENTER.

    A warning message appears.

  4. Click Yes.

  5. Double-click the Value column next to Custom Date/Time Format.

  6. Click HHMMSSDD in the value list and press ENTER.

    The new custom date/time data type is applied.

Important

  • If you want to express time up to the tenths or hundredths of a second, use the custom date/time data type described in this topic.

Notes

  • If you change the custom date and time to HHMMSSDD, the data type for the custom date/time property on the Parse tab changes to string.

  • If you use this custom date/time data type, you can send time in any one of the following formats:
    • HHMM

    • HHMMSS

    • HHMMSSD

    • HHMMSSDD

    The X12 parser and serializer read the custom date/time data type from left to right and will not return an error if the date and time sent are less than eight characters. For example, the following date and time data is valid:

    • 2211

    • 221101
  • If you use this custom date/time data type, time data content must always be sent and received in an even number of digits, with the exception of time data that is expressed in tenths of a second. For example, 2211 is valid time data, but 22115 is not.

  • This custom date/time data type is available only if the standard on which the schema is based is X12.

Related Topic

Supported Time Format for X12


Declare namespaces

  1. Click any node in the specification tree.

  2. Click the Namespace tab.

  3. Right-click the first blank field in the Prefix column and click Add.

  4. Type a namespace prefix and press ENTER.

  5. Double-click the field directly to the right, in the Uniform Resource Name column.

  6. Type a Uniform Resource Name and press ENTER.

Important

  • BizTalk Editor does not validate the Uniform Resource Name (URN) that you enter for a namespace.

  • Do not specify a namespace URN that begins with "x-schema:". If your specification contains x-schema, schema references will not be resolved by the run-time engine.

For more information about namespaces, see Namespace Declarations.

Related Topics

Add custom annotations

Character Length Limits

Delete custom annotations

Edit custom annotations

Namespace Declarations


Add custom annotations

  1. In the specification tree, click the root node, record, or field for which you want to add a custom annotation.

    Note

    • On the Reference tab, you cannot add a custom annotation for the root node.
  2. Click the Declaration tab or the Reference tab, depending on where you want to add the custom annotation.

  3. Right-click the first blank field in the Property column and click Add.

    Edit mode is activated in the Property column.

  4. Type a prefix:name pair (For example, bts:specification where bts is the prefix and specification is the name pair. You must separate the prefix and the name pair with a colon) and press ENTER.

    -Or-

    Click one of the custom annotations in the list and press ENTER.

  5. Double-click the blank field directly to the right, in the Value column.

  6. Type the value of the custom annotation and press ENTER.

Important

  • For the specification to compile successfully, the namespace prefix used in step 4 must be declared in the specification. For more information, see Declare namespaces.

Related Topics

Adding SQL Annotations

Declare namespaces

Delete custom annotations

Edit custom annotations

Namespace Declarations


Edit custom annotations

  1. In the specification tree, click the node that contains the custom annotation that you want to edit.

  2. Click the tab (Declaration or Reference) that references the custom annotation that you want to edit.

  3. Double-click the Property field of the custom annotation, edit the field, and then press ENTER.

  4. Double-click the Value field of the custom annotation, edit the field, and then press ENTER.

Related Topics

Adding SQL Annotations

Declare namespaces

Namespace Declarations


Delete custom annotations

  1. In the specification tree, click the node that contains the custom annotation that you want to delete.

  2. Click the tab (Declaration or Reference) that references the custom annotation that you want to delete.

  3. Right-click the custom annotation and click Delete.

  4. Click Yes to confirm the change.

Related Topics

Add custom annotations

Adding SQL Annotations

Declare namespaces.

Edit custom annotations

Namespace Declarations


Set dictionary properties

  1. In the specification tree, click the root node, record, or field for which you want to specify a property, and then click the Dictionary tab.

  2. In the Property column, select the check box for the value that you want to associate with the field.

The Dictionary tab contains the properties shown in the following tables. Dictionary properties can be set only for specifications with the Standard property on the Reference tab set to XML or CUSTOM.

Dictionary Tab: Root Node or Record Properties

Property | Node path
Document Container Node | In an envelope schema, the document node indicates the record that contains the document.

Note

  • In a flat-file specification (with its Standard property on the Reference tab set to CUSTOM) that is parsed by the BizTalk Server flat-file parser, selecting or clearing the Document Container Node dictionary property check box has no effect. This dictionary property is made available, however, in case you need to create a custom specification and a custom parser that use the Document Container Node dictionary property.

Dictionary Tab: Field Properties

Property | Node path
Document Name | Displays the path to the field of a document instance that contains the document name.
Source Type | Displays the path to the field of a document instance that contains the source type.
Source Value | Displays the path to the field of a document instance that contains the source value.
Destination Type | Displays the path to the field of a document instance that contains the destination type.
Destination Value | Displays the path to the field of a document instance that contains the destination value.

Notes

  • When parsing a specification, the parser uses information on the Dictionary tab to locate a channel. You can create a channel by using BizTalk Messaging Manager. For more information about channels and BizTalk Messaging Manager, see Understanding Channels.

  • If you use a specification to define documents that are submitted to an open messaging port, you must select the destination value on the Dictionary tab for the field that contains the destination and transport information. The destination information in a document is overwritten if you use submission parameters. For more information about submitting documents, see Submitting.

  • You can also set Dictionary properties by right-clicking a field in the Property column and clicking Set Routing Information.

Related Topics

Add a custom dictionary property

Character Length Limits

Clear a dictionary property

Delete a custom dictionary property

Rename a custom dictionary property

Submitting

Understanding Messaging Ports


Add a custom dictionary property

  1. In the specification tree, click the field for which you want to add a custom dictionary property.

  2. Click the Dictionary tab.

  3. Double-click the first blank field in the Property column.

  4. Type a name for the property and press ENTER.

Notes

  • Use a unique name for each custom property that you create.

  • The Standard property (for the root node) must not be set for X12 or EDIFACT.

Related Topics

Clear a dictionary property

Delete a custom dictionary property

Rename a custom dictionary property

Set dictionary properties


Rename a custom dictionary property

  1. Click the Dictionary tab.

  2. Right-click the custom property that you want to rename and click Rename.

  3. Type a name for the property and press ENTER.

Note

  • Use a unique name for each custom property that you create.

Related Topics

Add a custom dictionary property

Clear a dictionary property

Delete a custom dictionary property

Set dictionary properties


Clear a dictionary property

  1. In the specification tree, click the node for which you want clear a dictionary property and click the Dictionary tab.

  2. In the Property column, clear the check box for the value that you want to disassociate from the field.

Notes

  • You can also clear a Dictionary property value by right-clicking a field in the Property column and clicking Clear Routing Information.

  • By clearing a dictionary property in a node, you remove the routing information.

Related Topics

Add a custom dictionary property

Character Length Limits

Delete a custom dictionary property

Rename a custom dictionary property

Set declaration properties


Delete a custom dictionary property

  1. Click the Dictionary tab.

  2. Right-click the custom property that you want to delete and click Delete.

  3. Click Yes to confirm the change.

Related Topics

Add a custom dictionary property

Clear a dictionary property

Rename a custom dictionary property

Set dictionary properties


Select codes

  1. Click a field in a specification tree.

  2. Click the Code List tab.

  3. In the Value column, select the check box next to the code that you want to use.

Notes

  • Code lists are available only for specifications based on X12 or EDIFACT. However, not all fields in a specification based on X12 or EDIFACT have codes associated with them. A complete list of available codes for a specific field appears on the Code List tab. Codes are associated with a field if the check box in the Value field next to the code is selected. A description of the code appears in the Description field.

  • When you associate a code with a field on the Code List tab, that association is also shown on the Declaration tab. The Data Type value on the Declaration tab is automatically set to Enumeration, and Data Type Values shows the code list numbers you selected on the Code List tab. If you clear the Data Type value on the Declaration tab, there will be no codes selected on the Code List tab. For more information, see Clear a property for any field in the Value column.

  • To select a range of codes, select the check box next to a code, press SHIFT, and then select the check box next to a second code. All codes between the first code and the second code are selected.

  • Occasionally, duplicate code values appear on the Code List tab. These duplicate code values have varying descriptions, depending on the type of document with which the code value is associated. In the context of validating a document instance, it is never necessary to select more than one code value. However, it is possible to inadvertently select more than one code value. The following list summarizes the selection behavior of duplicate code lists:
    • If you select the top code value in a set of duplicate code values, only that code value is selected.

    • If you select any code value other than the top code value in a set of duplicate code values, this code value is selected and the top code value is automatically selected, too.

    • The top code value in a set of duplicate code values cannot be cleared while any other code values in the set are selected.

Related Topics

Clear a property for any field in the Value column

Clear codes

Code List Values and Descriptions


Clear codes

  1. Click a field in the specification tree.

  2. Click the Code List tab.

  3. In the Value column, clear the check box that is next to the code that you want to clear.

Notes

  • Code lists are available only for specifications based on X12 or EDIFACT. However, not all fields in a specification based on X12 or EDIFACT have codes associated with them. A complete list of available codes for a specific field appears on the Code List tab. Codes are associated with a field if the check box in the Value field next to the code is selected. A description of the code appears in the Description field.

  • Occasionally, duplicate code values appear on the Code List tab. These duplicate code values have varying descriptions, depending on the type of document with which the code value is associated. In the context of validating a document instance, it is never necessary to select more than one code value. However, it is possible to inadvertently select more than one code value. The following list summarizes the selection behavior of duplicate code lists:
    • If you select the top code value in a set of duplicate code values, only that code value is selected.

    • If you select any code value other than the top code value in a set of duplicate code values, the code value is selected and the top code value is automatically selected, too.

    • The top code value in a set of duplicate code values cannot be cleared while any other code values in the set are selected.

Related Topics

Code List Values and Descriptions

Select codes


Clear a property for any field in the Value column

  1. Click the tab that contains the property that you want to clear.

  2. Right-click the field in the Value column and click Clear Property.


Automatically calculate field positions

If the Custom Data Type value is set to implied decimal, then calculate field positions manually. For more information, see the Start Position and End Position information in Set reference properties.

  1. Select a field in a positional record.

  2. Double-click the Value field in the Data Type row.

  3. In the Data Type list, click a value.

    Note

    • To specify a Maximum Length value (steps 4 and 5), you must select one of the following Data Type values: String, Number, Binary (base64), or Binary (hex).
  4. Double-click the Value field in the Maximum Length row.

  5. Type a number into the Maximum Length Value field and press ENTER.

  6. Repeat steps 1 through 5 for each field in the record.

  7. Right-click the record and click Calculate Field Positions.

    The following warning appears:

    This operation will modify the Start Position and End Position properties for the fields in the selected record. Do you want to continue?

  8. Click Yes.

    The start and end positions are calculated for the fields in the record. For more information, see Calculating Field Positions.


Edit Notes and View Syntax Rules

In the Node Properties dialog box, you can:

  • Read and edit notes for fields and records.

  • Read syntax rules for records.

To view the Node Properties dialog box, follow these steps:

  1. In the specification tree, right-click a record or field and click Properties.

    The Note tab appears by default.

  2. To view syntax rules for a record, click the Syntax Rules tab.

Note

  • Syntax rules apply only to records.

For information about how to use this dialog box, see the following topics:

  • Enter Record Notes

  • View Syntax Rules

  • Enter Field Notes


Enter Record Notes

For information about how to open the Node Properties dialog box, see Edit Notes and View Syntax Rules.

You can use notes to record any information relevant to the record with which they are associated; for example, the purpose of the record or the reason why it was created.

  • To record a note, type some text in the Node Properties dialog box and click OK.

Notes

  • You cannot add a note to the root node.

  • You cannot type unprintable characters (typically any combination of the Alt key plus numbers) in notes. For instance, if you press ALT and then type 75, the letter K would appear.

Related Topics

Enter Field Notes

View Syntax Rules


View Syntax Rules

For information about how to open the Node Properties dialog box, see Edit Notes and View Syntax Rules.

Syntax rules provide information about how the specification tree must be organized. Syntax rules are found only in specifications based on the X12 standard.

  • To view syntax rules for a record, click the Syntax Rules tab.

Note

  • Syntax rules apply only to records.

Related Topics

Enter Field Notes

Enter Record Notes


Enter Field Notes

For information about how to open the Node Properties dialog box, see Edit Notes and View Syntax Rules.

You can use notes to record any information relevant to the field with which they are associated; for example, the purpose of the field or the reason why it was created.

  • To record a note, type some text in the Node Properties dialog box and click OK.

Note

  • You cannot type unprintable characters (typically any combination of the Alt key plus numbers) in notes. For instance, if you press ALT and then type 75, the letter K would appear.

Related Topics

Enter Record Notes

View Syntax Rules


Manage Document Instances

In BizTalk Editor you can create a document instance based on a specification and you can validate a document instance against a specification.

The following procedures are covered in this section:

  • Create a document instance

  • Create a native instance

  • Validate a document instance


Create a document instance

  1. Open a specification on which you want to base a document instance.

  2. On the Tools menu, click Create XML Instance.

    The Create Document Instance As dialog box appears.

  3. Browse to the folder in which you want to create a document instance.

  4. In the File Name box, type a name for the document instance and click Save.

    The new document instance is displayed on the Output tab.

Note

  • The only format available for creating a document instance is Unicode.

Related Topic

Validate a document instance


Create a native instance

  1. Open a specification.

  2. On the Tools menu, click Create Native Instance.

    The Create Native Document Instance As dialog box appears.

  3. Browse to the folder in which you want to create a native instance.

  4. In the File Name box, type a name for the native instance and click Save.

    The Document Delimiters dialog box appears.

  5. Select an option, or type a delimiter, from each of the following lists:
    • Record Delimiter

    • Field Delimiter

    • Subfield Delimiter

    • Escape Character

    Important

    • If you specify your own delimiters, use Unicode character values. For a list of valid characters, go to the Global codepages page on the Microsoft Global Software Development Web site ( www.microsoft.com/globaldev/reference/wincp.asp). You can use ANSI character codes, provided they are the same as the Unicode character code except for having two leading zeros.

Important

  • Although you might successfully create a native instance, if you later complete instance validation, it will fail if syntax rules are not followed.

  • Character ranges are ignored. Therefore, if they are not met, you will still successfully create a native instance, but later when BizTalk Server attempts to parse your transaction, it will fail.

  • The Create Native Instance feature will not create HHMMSSDD custom format.

  • A native instance might not be generated for a positional file if either of the following exists:
    • The Data Type value on the Declaration tab is not String, Number, Binary (base64), or Binary (hex).

    • The Maximum Length value on the Declaration tab does not contain a value.


Validate a document instance

  1. Open a specification against which you want to validate a document instance.

    For more information, see Open Specifications.

  2. On the Tools menu, click Validate Instance.

    The Validate Document Instance dialog box appears.

  3. Browse to the document instance you want to validate and click Open.

  4. If you validate a document instance that does not have an envelop against a specification based on either the X12 or EDIFACT standard, the Document Delimiters dialog box appears. Do one of the following:
    • X12-based specifications. Select the delimiters appropriate for the document you want to validate and click OK.

    • EDIFACT-based specifications. Select the delimiters and the escape character appropriate for the document you want to validate and click OK.
  5. View the message displayed on the Warning tab. If the document instance is validated against the specification, the following message displays:

    The document instance validation succeeded.

    If the document instance is not validated against the specification, the Warning tab indicates this and displays errors that indicate why the document instance was not validated. Resolve warnings and revalidate the document instance.

  6. If you validate a non-XML document instance against a non-XML specification and if the document instance is validated, click the Output tab to view an Extensible Markup Language (XML) version of the document.

International Issue

  • If you create a document instance containing a Japanese yen symbol or Korean won symbol while your system locale is set to Japanese or Korean, when that document instance is successfully validated against the corresponding specification, the yen symbol or won symbol appears as a backslash (\) on the Output tab of BizTalk Editor. To view the yen symbol or won symbol rather than a backslash, you can view the source of the Output tab.
    1. On the Output tab that displays a backslash rather than the yen symbol or won symbol, right-click anywhere within the tab, and then click View Source.

    2. In Notepad, on the Format menu, click Font.

    3. In the Font dialog box, in the Font area, click Tahoma, and then click OK.

Notes

  • It is important to understand issues with invalid XML name characters when validating instances. For more information, see Invalid XML Name Characters.

  • A well-formed XML document instance that contains elements typed as XML-Data Reduced (XDR) data types might not validate against its corresponding specification. To make such a document instance validate against its corresponding specification, ensure that all elements typed as XDR data types have their Model properties set to Open. For more information about the Model property, see Set declaration properties.

  • Non-XML document instances saved in Unicode will not validate correctly unless you remove the byte order marker at the beginning of the file. The byte order marker is the first two bytes of any files saved in Unicode.

  • A document instance that contains an "x-schema:" schema reference is always validated using that schema reference, regardless of the schema that is loaded in BizTalk Editor.

  • An invalid character map is not a criterion of instance validation. For example, if an instance contains data contained within the start range and end range in the Invalid Character Ranges dialog box, validation might still succeed.

Related Topics

Create a document instance

Invalid XML Name Characters

Validating Instances and Specifications


Manage Invalid Character Maps

The following procedures are covered in this section:

  • Add invalid character ranges

  • Edit invalid character ranges

  • Delete invalid character ranges


Add invalid character ranges

  1. On the View menu, click Invalid Character Map.

    The Invalid Character Ranges dialog box appears.

  2. Click the New Character Range button New Character Range button.

    The Enter Invalid Character Range dialog box appears.

  3. Select a value from the Invalid start range list and press TAB.

  4. Select a value from the Invalid end range list and click OK.

  5. Repeat steps 2 through 4 to add additional invalid character ranges.

Important

  • You can set invalid character ranges only for non-XML documents.

  • The correct hexadecimal value for a question mark symbol (?) is (0x3f). The default setting in the Invalid start range list and Invalid end range list is ? (0x0). Do not use this to represent a question mark symbol. To specify a question mark symbol, select the ? (0x3f) value from the list.

Notes

  • The values that appear in the Invalid start range and Invalid end range lists are hexadecimal values. If you view the specification as an Extensible Markup Language (XML) source file by using an application such as Microsoft Internet Explorer 5 or later, the values appear as decimal values. For example, if you type a semicolon (;) in the Invalid start range and Invalid end range boxes, the value that appears is ; (0x3b). Viewed by using a browser, this value appears as 59.

  • To enter an invalid character range, you can also highlight the value in the Invalid start range list, type a numeric or alphabetic character, and then press TAB to move to the Invalid end range list.

Related Topics

Delete invalid character ranges

Edit invalid character ranges


Edit invalid character ranges

  1. On the View menu, click Invalid Character Map.

    The Invalid Character Ranges dialog box appears.

  2. Select the character range that you want to modify and click the Change Character Range button Change Character Range button.

    The Enter Invalid Character Range dialog box appears.

  3. In the Invalid start range list, select a value.

    –Or–

    In the Invalid end range list, select a value.

  4. Click OK.

  5. Repeat steps 2 through 4 to modify additional invalid character ranges.

Important

  • You can set invalid character ranges only for non-XML documents.

  • The correct hexadecimal value for a question mark symbol (?) is (0x3f). The default setting in the Invalid start range list and Invalid end range list is ? (0x0). Do not use this to represent a question mark symbol. To specify a question mark symbol, click the ? (0x3f) value in the list.

Notes

  • The values that appear in the Invalid start range and Invalid end range lists are hexadecimal values. If you view the specification as an XML source file by using an application such as Microsoft Internet Explorer 5 or later, the values appear as decimal values. For example, if you type a semicolon (;) in the Invalid start range and Invalid end range boxes, the value that appears is ; (0x3b). Viewed by using a browser, this value appears as 59.

  • To enter a character range, you can also highlight the value in the Invalid start range list, type a numeric or alphabetic character, and then press TAB to move to the Invalid end range list.

Related Topics

Add invalid character ranges

Delete invalid character ranges


Delete invalid character ranges

Important

  • You can set invalid character ranges only for non-XML documents.
  6. On the View menu, click Invalid Character Map.

    The Invalid Character Ranges dialog box appears.

  7. Click the character range that you want to delete and click the Delete Character Range button Delete Character Range button.

  8. Click Yes to confirm the change.

Related Topics

Add invalid character ranges

Edit invalid character ranges


Manage Views

The following procedures are covered in this section:

  • Expand tree items

  • Collapse tree items

  • View property values

  • Change text sizes


Expand tree items

  • Click the root node or record that you want to expand and, on the View menu, click Expand Tree Items.

Note

  • To expand the entire tree, you must click the root node. If you click a record, you expand only the child records and fields within the record.

Related Topic

Collapse tree items


Collapse tree items

  • Click the root node or record that you want to collapse and, on the View menu, click Collapse Tree Items.

Note

  • To collapse the entire tree, you must click the root node. If you click a record, you collapse only the child records and fields within the record.

Related Topic

Expand tree items


View property values

  • On the View menu, click one of the following properties:
    • Declaration

    • Reference

    • Parse

    • Namespace

    • Dictionary

    • Code List


Change text sizes

  • On the View menu, point to Text Size and click the size that you want.


BizTalk Editor Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Editor. The following table is a quick reference to these shortcut keys.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server and Advanced Server Help, see "Using the keyboard to move the mouse pointer." For more information about MouseKeys in Windows 2000 Professional Help, see "Move the mouse pointer by using MouseKeys."
Press | To
CTRL+SHIFT++ (With the NUMLOCK key enabled, press the + key on the number pad while pressing the SHIFT key.) Add a new custom annotation when the focus is on the namespace data sheet in the right pane.

Or

Create a new custom property on the Declaration, Reference, Namespace, or Dictionary tab.

Or

Insert a custom property in a specification. This functionality occurs on the Declaration, Reference, Namespace, and Dictionary tabs while a property is highlighted.
TAB key | Access the buttons in the upper right corner of the New Document Specification dialog box.
SHIFT+F10 | Open the context menu for highlighted items.
CTRL+N | Open a new specification.
CTRL+O | Open an existing specification.
CTRL+S | Save a specification.
CTRL+SHIFT+R | Insert a new record into a document specification.
CTRL+R | Add a new record to a record.
CTRL+SHIFT+F | Insert a new field into a document specification.
CTRL+F | Add a new field to a record.
DEL | Delete a record or a field.
F4 | Highlight the next warning.
F5 | Validate a schema.
CTRL+C | Copy an object.
CTRL+X | Cut an object.
CTRL+V | Paste an object.
F6 | Move the focus clockwise from pane to pane.
SHIFT+F6 | Move the focus counterclockwise from pane to pane.
TAB | Toggle the focus from the tab in the right pane to the data sheet below. In a dialog box, pressing TAB moves the focus through the buttons and fields of the dialog box.
SPACEBAR | Select or clear a check box. The spacebar also acts like a mouse click when the focus is on a button.
F2 | Activate edit mode for a highlighted node in the specification tree. Activate edit mode for a highlighted row in the data sheet of the right pane.
SHIFT+F2 Activate edit mode for the following fields:
  • The Property column of a highlighted custom annotation row on the Declaration or Reference tab.

  • The Prefix column of a highlighted custom annotation row on the Namespace tab.

  • The Property column of a highlighted custom dictionary row on the Dictionary tab.
ALT+ DOWN ARROW | Display the list for an activated list box.
SHIFT++ | Add a new custom annotation when the focus is on the namespace data sheet in the right pane.
ENTER | Confirm edits to nodes and values.
ESC | Cancel edits to nodes and values.
F1 | View the online Help.
ALT+F4 | Exit from the program.
LEFT ARROW | Activate the tab to the left.
RIGHT ARROW | Activate the tab to the right.
Any arrow key | Highlight a folder or a file in the main pane of a dialog box, while the focus is on that pane. This functionality occurs in the New Document Specification, the Store to WebDAV, and the Retrieve from WebDAV dialog boxes. For more information about the New Document Specification dialog box, see Create and Validate Specifications. For more information about WebDAV, see Open existing specifications from WebDAV.

Using MouseKeys with BizTalk Editor

Some operations in BizTalk Editor have no keyboard shortcuts. To perform the following operations, you must use MouseKeys:

  • Move

  • Drag-and-drop operations

  • Copy nodes


Using BizTalk Mapper

Microsoft® BizTalk™ Mapper is a translation design tool that enables you to create a correspondence between the records and fields in two different specification formats. BizTalk Mapper uses links and functoids to accomplish this translation. Functoids perform operations that range from simple calculations to elaborate script functionality.

You can use BizTalk Mapper to graphically represent the structural transformation relationship between source-specification data elements and destination-specification data elements. This cross-reference and data-manipulation functionality creates a map that provides a set of instructions that defines the relationship between two different specification formats. The specification formats are defined by using BizTalk Editor.

A map represents data transformations between a source specification and a destination specification. Microsoft BizTalk Server 2002 uses the data that you provide in a map to generate Extensible Stylesheet Language Transformation (XSLT). Then, the XSLT output is used by Microsoft XML Parser (MSXML) version 3.0 at run time to transform the schema on the server. When you create a map, the XSLT can be viewed on the Output tab of BizTalk Mapper.

BizTalk Mapper enables the open exchange of specifications in an XML-Data Reduced (XDR) data format. BizTalk Mapper can open only specifications that have been saved in BizTalk Editor. BizTalk Mapper cannot open generic Extensible Markup Language (XML) files or non-XML files. If you need to translate two generic XML files, you must first import them into BizTalk Editor and save them as specifications.

BizTalk Mapper supports a variety of mapping scenarios that range from simple, parent-child tree relationships to detailed, complex looping of records and hierarchies. When the mapping process is complete, a serializer component uses the specification to create a file format that can be recognized by your trading partner or internal application. BizTalk Mapper also includes a style-sheet compiler component that takes the visual representation of the map and creates an XSLT style sheet.

The following illustration shows the process of mapping a source specification to a destination specification. The source file is an electronic data interchange (EDI)-based document, and the destination file is a flat-file document. In this example, the EDI document structure is converted to an intermediate XML format, the structure of which is represented by an XDR specification. The final format of the data is a flat file. A data-driven parser (that uses the XDR specification) creates an XML version of the source EDI specification. The XSL engine then transforms this source XML representation to an XML representation of the destination file format. The destination specification is later serialized to the native format of the destination file, which is a flat file in this example.

Transforming an EDI document into a flat-file document

The following topics are covered in this section:

  • For comprehensive information about BizTalk Mapper, see About BizTalk Mapper.

  • For quick reference about why you perform specific tasks, see Why Perform BizTalk Mapper Tasks.

  • For detailed procedures on how to accomplish tasks, see How to Perform BizTalk Mapper Tasks.

  • For problem-solving instructions, see Troubleshooting BizTalk Editor and BizTalk Mapper.


About BizTalk Mapper

BizTalk Mapper is a highly graphical tool that presents you with both source specifications and destination specifications side-by-side and lets you define transformations by simply drawing lines between records, fields, and functoids. BizTalk Mapper uses an Internet standard called Extensible Stylesheet Language (XSL) Transformations (XSLT), which is a language for transforming Extensible Markup Language (XML) documents from one XML schema into another.

This section provides detailed conceptual information that is essential to understanding BizTalk Mapper.

The following topics are covered in this section:

  • Mapping Specifications

  • Mapping Scenarios

  • BizTalk Mapper Environment

  • Creating Links

  • Matching Node-Hierarchy Levels

  • Viewing Record, Field, Link, and Functoid Properties

  • Understanding Functoids

  • Integrating BizTalk Services Using Maps

  • Compiling Maps

  • Testing Maps


Mapping Specifications

A map identifies how data in one format is to be rendered in another format. A map requires two specifications: one is the source, and the other is the destination. Mapping data is a data-translation process in which you define the correspondences between the records and fields in the source specification and the records and fields in the destination specification.

There are two types of mapping:

  • Specific mapping. This type of map is designed to meet the individual needs of one trading partner. When you map a trading partner's specific record and field requirements, you create a map that is unique and specific to that trading partner only.

  • Generic mapping. This type of map is designed to meet the needs of several trading partners. In generic mapping, you group the requirements of multiple trading partners in one map. Because multiple organizations can be interconnected, and you can use the same map with multiple trading partners, this feature saves you valuable resources and time.

BizTalk Mapper shows a graphical representation of a map that can include simple value-copy translations, referred to as links, and complex structural manipulations, referred to as functoids. By combining these elements, you can easily map data between a source specification and a destination specification.

The following topic is covered in this section:

  • Map Source and Destination Files


Map Source and Destination Files

Maps are Microsoft BizTalk Server-specific Extensible Markup Language (XML) files that are created by BizTalk Mapper. You can create maps that are based on:

  • Industry standards (such as XML, EDIFACT, or X12)

  • Non-industry standards (such as delimited flat files, positional flat files, or delimited and positional flat files)

  • Existing files

BizTalk Mapper also supports using non-BizTalk Server schemas for the creation of maps. To create a map, you must use two specifications: one for the Source Specification tree and one for the Destination Specification tree.

Existing BizTalk Server 2000 files

Maps from BizTalk Server 2000 are almost entirely compatible with BizTalk Server 2002. If you open and save a map in BizTalk Server 2002 that you created in BizTalk Server 2000, the file format will be changed and you will not be able to open it using BizTalk Server 2000.


Mapping Scenarios

BizTalk Mapper addresses a variety of mapping scenarios ranging from simple parent-child tree-type operations to detailed operations that are complex and involve looping records, and hierarchies. The complexity of mapping scenarios is further complicated because formats like Extensible Markup Language (XML) allow for a great deal of flexibility in defining structured formats.

Basic mapping operations

These are the most common mapping operations and involve the mapping of a source field or fields from a single parent in the Source Specification tree to a field or fields in the Destination Specification tree belonging to a single parent. Though there are a wide variety of transformations possible in this type of mapping, such as using multiple functoids and cascading functoids, the fundamental scenario is not complicated when compared with other scenarios. Basic mapping operations also include the mapping of fields from two different parents (that occur only once) to fields in the Destination Specification tree under a single parent.

Complex mapping operations

Theses operations may involve mapping fields from different parents (one of which can occur multiple times) in the Source Specification tree to a single parent in the Destination Specification tree. This type of mapping requires the proper selection of a loop path, which is commonly encountered in mapping electronic data interchange (EDI)-based documents. This scenario would require the Extensible Stylesheet Language (XSL) style sheet compiler to pick up the correct loop path over which it must iterate to produce the required output. For more information about loop paths, see Loop Paths.

The following topics are covered in this section:

  • Loop Paths

  • Ordering of Records and Fields


Loop Paths

A record in a specification is looping if the Maximum Occurrences property on the Reference tab for that record is set to an asterisk (*). For more information about the Maximum Occurrences property, see Set reference properties.

A loop path occurs in a map when a field contained by a looping record in the source specification is linked to a field contained by a looping record in the destination specification. The following illustration shows two loop paths, one from Root\Record1\Field1 to Root\RecordA\Field1, and the other from Root\Record2\Field2 to \Root\RecordB\Field3.

Loop path map

The Properties tab shows Record1 and RecordA to be looping in the Maximum Occurrences property. Record2 and RecordB are also looping.

The following code is a sample input document:

<Root>
<Record1 Field1="Red">
<Record1 Field1="Green">
<Record1 Field1="Blue">
<Record2 Field2="50">
<Record2 Field2="100">
</Root>

Using the previous map, this input document would map to the following output document:

<Root>
<RecordA Field1="Red">
<RecordA Field1="Green">
<RecordA Field1="Blue">
<RecordB Field3="50">
<RecordB Field3="100">
</Root>

Multiple Loop Path

A multiple loop path occurs in a map when fields contained by two or more looping records in the source specification are linked to fields contained by a single looping record in the destination specification.

The following illustration shows an example of a multiple loop path.

Multiple loop path map

Multiple loop paths are not supported in BizTalk Mapper. If you attempt to compile a map that contains a multiple loop path, the Warnings tab indicates that the destination node has multiple source loop paths.

Related Topics

Set reference properties

Using the Looping Functoid


Ordering of Records and Fields

An implied order of output records and fields is not guaranteed in Extensible Stylesheet Language (XSL). This is because BizTalk Mapper generates XSL by walking the destination specification structure and then propagating back through the mapping grid to extract values from the source specification structure. For example, if you want to create an output file that has BillTo Address records listed first, followed by ShipTo Address records, you must ensure that the BillTo Address precedes the ShipTo Address record in the destination specification.

The following illustration shows this structure.

The ContactType field contains two valid codes (BT and ST) that identify the address as either a BillTo address or a ShipTo address. To create the wanted output, Equal functoids are added to the mapping grid and linked from fields in the source specification to records in the destination specification.

In the map, the first functoid checks for the following condition:

Is ContactType equal to BT?

If this condition is satisfied, an output record, BillToAddresses, is created and the required fields are mapped to it. If the condition is not met, BizTalk Mapper must reiterate all the input address records to satisfy the required condition.

Important

  • The order in which records and fields appear in an output document instance is dependent on the order of the records and fields of the corresponding output specification.


BizTalk Mapper Environment

When you open BizTalk Mapper, you see a graphical user interface that enables you to create and work with maps easily.

The following topics are covered in this section:

  • BizTalk Mapper User Interface

  • BizTalk Mapper Menus

  • BizTalk Mapper Toolbar Buttons

  • BizTalk Mapper Functoid Palette

  • Customizing Your Display


BizTalk Mapper User Interface

The two specifications that are used to create a map appear as tree views in the main window of BizTalk Mapper. The source specification from which the data is mapped from is on the left, and the destination specification to which the data is mapped to is on the right. The mapping grid between the two specifications graphically displays the structural data transformation between the two specifications. Links and functoids appear in the mapping grid. You can easily move up, down, left, or right in the mapping grid by moving the pointer to the borders of the mapping grid. You can also add additional grid pages so that you can keep your links and functoids grouped together and to simplify the view of various areas of your map. For example, you might want to separate the header section of a map from the body.

You can use the Grid Preview dialog box to move quickly from one location in the mapping grid to another. By dragging the green locator bar, you can move up, down, left, or right. A functoid in the mapping grid appears in the preview grid as a red box that is surrounded by a black outline. If there are two or more functoids in the mapping grid, the graphic appears as two red boxes attached to one another, surrounded by a black outline.

Beneath the tree views and mapping grid is the lower pane. This area has four tabs:

  • Properties. When you select a node in the Source Specification tree or the Destination Specification tree, the Properties tab displays the properties and property values for that node.

  • Values. This tab has two text boxes, Source test value and Destination constant value. You can select a field and then type a value in the Source test value box. This enables you to test maps with actual values assigned to fields. In the Destination constant value box, you can specify a value to assign to a field. You cannot create a link from a functoid or from a node in the source specification to a field with a constant value assigned to it.

  • Output. This tab displays a compiled Extensible Stylesheet Language (XSL) style sheet when you compile a map, and it displays test map output when you test a map.

  • Warnings. This tab displays compiler warnings after you compile a map. If you select a warning in this area, the associated link or functoid is highlighted in your map so you can locate and resolve errors.

Related Topics

Compiling Maps

Testing Maps

View links and functoids by using the grid preview


BizTalk Mapper Menus

BizTalk Mapper menus logically group commands together, making it easy to perform a specific task. For example, you can use the commands on the View menu to view all the records and fields in the Source Specification tree or to collapse all the records and fields in the Destination Specification tree.

The BizTalk Mapper menus are as follows:

  • File. Use this menu to create, open, save, or close a map.

  • Edit. Use this menu to replace the source or destination specification, to delete an object in the mapping grid, or to add or delete grid pages.

  • View. Use this menu to view the functoid palette, the functoid properties, and the grid preview, as well as to select a text size for the BizTalk Mapper display, to activate tabs in the lower pane, to expand or collapse the specification trees, or to highlight the next warning on the Warnings tab.

  • Tools. Use this menu to compile and test your maps, and to view BizTalk Mapper options.

  • Help. Use this menu to get conceptual information, understand why tasks are important, and view procedural content about using BizTalk Mapper.

Related Topic

BizTalk Editor Menus


BizTalk Mapper Toolbar Buttons

BizTalk Mapper provides a toolbar to complement the menu bar. All of the toolbar buttons display graphical representations of the tasks they perform. They appear in the following order from left to right:

  • New

  • Open

  • Save

  • Retrieve from WebDAV

  • Store to WebDAV

  • Delete

  • Collapse

  • Expand

  • View Functoid Palette

  • Compile Map

  • Test Map

  • Add Page

  • Delete Page


BizTalk Mapper Functoid Palette

The functoid palette contains all the functoids available in BizTalk Mapper. A functoid contains code that takes data from a record or field in the source specification, or from another functoid (such as a Date functoid), processes the data independently, and then returns a new value that is placed in a record or field in the destination specification. For more information about the functoid palette, see Understanding Functoids.

Related Topics

Understanding Functoids

Work with Functoids


Customizing Your Display

You can customize the look of BizTalk Mapper in several ways. For example, you can change the background mapping grid colors, specify new colors for links and selected objects, change the color of compiler warnings, and modify the size of text. The following items can be customized:

  • Grid foreground. The dashed lines in the mapping grid.

  • Grid background. The background color of the mapping grid.

  • Fixed links. Value-copy links in the mapping grid.

  • Elastic links. Value-copy links that are dragged from the Source Specification tree to the Destination Specification tree.

  • Partial links. Links for a field or record whose parent-record node is collapsed.

  • Compiler links. Compiler directive links, which are automatically created when you compile by pressing F5.

  • Compiler warnings. When you select a warning, which was generated when you compiled a map, on the Warnings tab, the link or functoid will be highlighted using the color specified for compiler warnings.

  • Selected objects. Any object, such as a functoid or link, you select in the mapping grid will be displayed using this color.

These features are available in the Options dialog box, which is accessible through the Tools menu. You can also make changes to text size from the View menu.

Related Topic

BizTalk Mapper Options: Colors Tab


Creating Links

Links perform the basic function of copying data from the Source Specification tree records and fields to the Destination Specification tree records and fields. BizTalk Mapper supports one-to-one links and one-to-many links. For example, a link can join a single record or field from the Source Specification tree to a single record or field in the Destination Specification tree. A link can also join a single record or field from the Source Specification tree to multiple records or fields in the Destination Specification tree. Links can also join multiple records or fields from the Source Specification tree to a functoid, which then joins to a single record or field in the Destination Specification tree. Multiple records or fields from the Source Specification tree can join to a single record or field in the Destination Specification tree.

Related Topic

Manage Links


Matching Node-Hierarchy Levels

BizTalk Mapper includes compiler directives. Using these directives, you can set the level of matching between the hierarchy of the Source Specification tree and the hierarchy of the Destination Specification tree. When you create a link from one field in the Source Specification tree to a field in the Destination Specification tree, BizTalk Mapper automatically adds compiler links based on the choices you make in the Destination Specification Links area on the Compiler tab of the Link Properties dialog box. For more information, see Select compiler properties for destination-specification links. The following illustrations show the node-hierarchy level matches that are possible:

  • Flatten link (default mode). This mode means that all the source hierarchies are flattened to the parent record of the destination node. In the first case, the source specification is more complex than the destination specification. In the second case, the destination specification is more complex.

Flatten link in which the Source Specification tree is more complex than the Destination Specification tree.

Flatten link in which the Destination Specification tree is more complex than the Source Specification tree.

  • Match links top-down. This mode matches level to level from the top down. In the first case, the source specification is more complex than the destination specification. In the second case, the destination specification is more complex.

Match links top-down in which the Source Specification tree is more complex than the Destination Specification tree.

Match links top-down in which the Destination Specification tree is more complex than the Source Specification tree.

  • Match links bottom-up. This mode matches level to level from the bottom up. In the first case, the source specification is more complex than the destination specification. In the second case, the destination specification is more complex.

Match link bottom-up in which the Source Specification tree is more complex than the Destination Specification tree.

Match links bottom-up in which the Destination Specification tree is more complex than the Source Specification tree.

The following table shows how BizTalk Mapper treats links based on the type of directive used.

For example, if you use a flatten compiler directive, a top-down compiler directive, and a bottom-up compiler directive for links from fields in the source specification to fields in the destination specification that share the same parent record, BizTalk Mapper treats all the links as if they were set to the flatten compiler directive.

Flatten | Top-down | Bottom-up | Result
1 | 1 | 1 | BizTalk Mapper treats all the links as if they were set to the flatten compiler directive.
1 or more | 1 |  | BizTalk Mapper treats all the links as if they were set to the top-down compiler directive.
1 or more |  | 1 | BizTalk Mapper treats all the links as if they were set to the bottom-up compiler directive.
 | 1 or more | 1 or more | BizTalk Mapper treats all the links as if they were set to the flatten compiler directive.

Related Topic

Compiling Maps


Viewing Record, Field, Link, and Functoid Properties

The source specification and destination specification display the records and fields associated with a specification. You can build these specifications using BizTalk Editor, or you can import them into BizTalk Editor as well-formed XML, a document type definition (DTD), or an XDR schema. You can use any XDR schema created by a third-party organization. However, group and namespace support are not provided. The source specification appears on the left of the mapping grid, and the destination specification appears on the right of the mapping grid.

Record and field properties and values

The properties and values for records and fields appear on the Properties tab, which is located below the main pane. When you select a record or field, the key properties and values from the property tabs of BizTalk Editor appear.

Link and functoid properties

The mapping grid of BizTalk Mapper graphically depicts the structure of the data transformation. A link appears as a single line that connects a record or field in the Source Specification tree to a record or field in the Destination Specification tree. Links are also used to connect records or fields to functoids. Functoids appear as icons. Properties for links include source and destination data and compiler directive information. Properties for functoids include input parameter and script information.

Related Topics

Records, Fields, and Properties

Understanding Functoids


Understanding Functoids

BizTalk Mapper supports complex structural transformations from records and fields in the Source Specification tree to records and fields in the Destination Specification tree. Functoids perform calculations by using predefined formulas and specific values, called arguments. These calculations are executed based on the designated order of the records and fields.

By selecting a functoid from the functoid palette, dragging it to the mapping grid, and linking it to elements in the Source Specification and Destination Specification trees, data can be added together, date or time information can be modified, data can be concatenated, or other operations can be performed. For example, the Addition functoid adds values.

The Functoid Palette includes the following tabs:

  • String. These functoids manipulate data strings by using string functions. For example, the String Find functoid finds one text string within another text string, and returns the position of the first character of the found string. To understand the parameter requirements for each string functoid, see String Functoids.

  • Mathematical. These functoids perform calculations by using specific values, called arguments, in a particular order, or structure. For example, the Addition functoid adds the values of the designated fields or records. To understand the parameter requirements for each mathematical functoid, see Mathematical Functoids.

  • Logical. These functoids perform specific logical tests. If a logical functoid is connected to a record in the destination specification and returns the value "true", the corresponding record in the output document is generated. If a logical functoid is connected to a record in the destination specification and returns the value "false", the corresponding record in the output document is not generated. The output of a logical functoid can also be accepted as input for other functoids in a map. If both a logical functoid and a looping functoid are linked together and then linked to a record in the Destination Specification tree, the looping functoid is used only when the logical functoid output is "true". To understand the parameter requirements for each logical functoid, see Logical Functoids.

    Important

    • If you link two records or fields in the Source Specification tree to two different logical functoids, and then link each of the logical functoids to the same record in the Destination Specification tree, only the first logical functoid will be used in the generated Extensible Stylesheet Language (XSL) Transformation (XSLT). The second link, from the second logical functoid, will be ignored.
  • Date/Time. These functoids manipulate date and time data or add current date, time, or date and time data to a record or field in the destination specification. To understand the parameter requirements for each date and time functoid, see Date and Time Functoids.

  • Conversion. These functoids closely match engineering functions such as DEC2HEX, which returns a hexadecimal value when given a decimal value. They can also be used to convert a character to its ASCII value or a value to the corresponding ASCII character. To understand the parameter requirements for each conversion functoid, see Conversion Functoids.

  • Scientific. These functoids convert a numeric value to a scientific value. For example, the Cosine functoid takes a value in radians from a field or record and returns the value of the cosine. To understand the parameter requirements for each scientific functoid, see Scientific Functoids.

  • Cumulative. These functoids return the sum, average, minimum, or maximum input of a looping record. To understand the parameter requirements for each cumulative functoid, see Cumulative Functoids.

  • Database. These functoids extract data from a database. To understand the parameter requirements for each database functoid, see Database Functoids.

  • Advanced. This tab has a several functoids that perform various manipulations. For example, there is a functoid that can use custom Microsoft® Visual Basic® script or Microsoft JScript®, functoids for value mapping, looping functoids, index functoids, iteration functoids, and functoids for managing and extracting information from record loops. To understand the parameter requirements for each advanced functoid, see Advanced Functoids.

You can also create your own custom functoids. For a sample of a custom functoid, go to the \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\SampleFunctoid folder. You can also look at a Microsoft® .NET-based sample functoid in the \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DateFunctoidNet folder on a computer with a complete installation of BizTalk Server or a custom installation of BizTalk Server that includes Messaging samples.

Important

  • If you create a custom functoid, you must register it on every computer where you want it to display and function properly. If a custom functoid is not registered on a computer and it is used in a map, the custom functoid will appear with the letters "FT". You will not be able to move the functoid, even though it will appear in the grid page.

The following topics are covered in this section:

  • Using Cascading Functoids

  • Using Cumulative Functoids

  • Using Database Functoids

  • Using the Record Count Functoid

  • Using the Index Functoid

  • Using the Iteration Functoid

  • Using the Value Mapping Functoid

  • Using the Value Mapping (Flattening) Functoid

  • Using the Looping Functoid


Using Cascading Functoids

Cascading functoids enable you to create maps for which you must link fields or records to multiple functoids to produce the necessary output in a field or record in the destination specification. Cascading functoids make it easy to create multiple, consecutive transformations in the mapping grid. Functoids are cascaded when one functoid is linked to another functoid before it is linked to a record or field in the destination specification. For example, you can create cascading functoids in which two concatenated strings are used to produce a third string that is fed into a field in the destination specification. There is no limit to the number of functoids you can cascade together in the mapping grid; however, complex cascading scenarios might result in poor performance.


Using Cumulative Functoids

Cumulative functoids operate within the context of the record level in the source specification. Certain records typically occur many times in an input file. For example, in a purchase order, the Item section might occur many times. The Item section might include products, descriptions, prices, and quantities. The following code is an example of a purchase order:

<PurchaseOrder>
  <From>Kevin F. Browne</From>
  <To>Northwind Traders</To>
<LineItems>
  <Item>
    <Product>Computer A</Product>
    <Description>laptop computer</Description>
    <Price>2000</Price>
    <Quantity>1</Quantity>
  </Item>
  <Item>
    <Product>Computer A Case</Product>
    <Description>laptop computer case</Description>
    <Price>50</Price>
    <Quantity>2</Quantity>
  </Item>
  <Item>
    <Product>Cleaner A</Product>
    <Description>computer monitor cleaner</Description>
    <Price>2</Price>
    <Quantity>100</Quantity>
  </Item>
</LineItems>
</PurchaseOrder>

The following illustration shows this purchase order displayed in BizTalk Editor.

Purchase order specification

The Maximum Occurrences property on the Reference tab for the Item record is set at an asterisk (*). This indicates that the item record loops, and BizTalk Mapper compiles this record as a loop.

You might want to find the sum total of all the line items in the purchase order and map the cumulative total into a field in an output document. To do this, you must first calculate the extended price for each item record in the purchase order and then aggregate the individual item record totals as the mapping progresses through all the item records in the purchase order.

The following illustration shows a Multiplication functoid and a Cumulative Sum functoid used to aggregate item records from an incoming purchase order and output the results in the POTotal field of a TotalsDocument document.

In this example, all the Item records that exist under the LineItems record of an incoming purchase order participate in the cumulative operation. The Price and Quantity fields are sent to a Multiplication functoid. The output of the Multiplication functoid becomes the input of the Cumulative Sum functoid. The output of the Cumulative Sum functoid is the accumulated value as the Item records are traversed in the input purchase order. This value is sent to the POTotal field of the TotalsDocument document and is the sum of each of the individual products of price and quantity: (2000x1)+(50x2)+(2x100)=2300.

Notes

  • The cumulative aggregation of a particular input takes place over the parent record from which the input link originates. This also applies to functoid outputs that are fed as input to a cumulative functoid.

  • Cumulative functoids ignore non-numeric input. For example, an input value of "three" is ignored.

The Cumulative Average, Cumulative Minimum, and Cumulative Maximum functoids behave similarly to the Cumulative Sum functoid. The Cumulative String functoid behaves differently from the rest of the cumulative functoids in that it concatenates strings rather than aggregating numeric values.

Related Topics

Add cumulative functoids

Cumulative Functoids


Using Database Functoids

Database functoids extract data from a database. To understand how database functoids are used, consider a large retail manufacturer with many stores spread over a large geographical area. Each store is designated by a numeric code, and an address list is distributed to all partners. The address list might contain the following structure:

StoreID: 123

Name: Contoso, Ltd

Address: 1234 Main Street

City: Denver, Colorado

PostalCode: 97402

PhoneNumber: 801-555-0179

StoreManager: Anthony Chor

In subsequent transactions, only the numeric code that represents the store is sent in a purchase order. BizTalk Mapper uses that code to extract the address information from a database. The following illustration shows such a scenario.

Database functoid map

In this illustration, the source specification represents an incoming purchase order, and the destination specification represents an invoice. The Database Lookup functoid Database Lookup functoid performs a database lookup to find the appropriate record from the appropriate table. The output of the Database Lookup functoid can be connected only to Value Extractor functoids Value Extractor functoid. The Value Extractor functoids extract the appropriate column name from the lookup record. The Error Return functoid Error Return functoid outputs a string containing error information if there are errors (such as connection failures) at run time.

The Database Lookup functoid requires four input parameters, in the following order:

  1. The lookup value

  2. The database connection string

  3. The table name

  4. The column name for the lookup value

For information about inserting, deleting, and moving input parameters, see Input Parameters.

In the previous example, the first input parameter is taken from the StoreID field of the incoming purchase order, and the remaining three input parameters are constants on the General tab of the Functoid Properties dialog box for the Database Lookup functoid. It is possible to create links from the Source Specification tree to supply values for all four input parameters. For more information about inserting, deleting, and moving input parameters, see Input Parameters.

The Value Extractor functoid requires the following two input parameters, in the following order:

  1. A link to the Database Lookup functoid

  2. The column name

The Error Return functoid requires exactly one input parameter: a link to the Database Lookup functoid.

Notes

  • Some Microsoft® SQL Server™ data types, such as text, ntext, and image, cannot be used as lookup values for the Database Lookup functoid.

  • If there is more than one record that matches the input parameters of the Database Lookup functoid, the Value Extractor functoid extracts only the first record in the table.

Related Topics

Database Functoids

Input Parameters


Using the Record Count Functoid

The Record Count functoid operates within the context of the record level in the source specification. Certain records typically occur many times in an input file. For example, in a purchase order, the Item section might occur many times. The Item section might include products, descriptions, prices, and quantities. The following code is an example of a purchase order:

<PurchaseOrder>
  <From>Kevin F. Browne</From>
  <To>Northwind Traders</To>
<LineItems>
  <Item>
    <Product>Computer A</Product>
    <Description>laptop computer</Description>
    <Price>2000</Price>
    <Quantity>1</Quantity>
  </Item>
  <Item>
    <Product>Computer A Case</Product>
    <Description>laptop computer case</Description>
    <Price>50</Price>
    <Quantity>2</Quantity>
  </Item>
  <Item>
    <Product>Clearner A</Product>
    <Description>computer monitor cleaner</Description>
    <Price>2</Price>
    <Quantity>100</Quantity>
  </Item>
</LineItems>
</PurchaseOrder>

The following illustration shows this purchase order displayed in BizTalk Editor.

Purchase order specification

The Maximum Occurrences property on the Reference tab for the Item record is set at an asterisk (*). This indicates that the Item record loops, and BizTalk Mapper compiles this record as a loop.

You might want to find the total number of line items in the purchase order and map that value into a field in an output document. This scenario is a bit different from the conventional mapping scenario in which content from the source document is mapped to the output document. In this case, the Record Count functoid generates the value that is mapped to the output document.

The Record Count functoid has one input and one output. The input is a link from a looping record in the source specification. This record appears many times in the original input document. The output of the Record Count functoid is a link to a field in the destination specification.

The following illustration shows a Record Count functoid that counts the number of items that exist in an incoming purchase order and outputs that value to the Number_Of_Items field in the POReport document.

Record Count functoid map

Because, in this example, there were three items in the incoming purchase order, the value of the Number_Of_Items field is 3.

Related Topic

Advanced Functoids


Using the Index Functoid

The Index functoid operates within the context of the record level of the source specification. Certain records typically occur many times in an input file. For example, in a weather report, the DailySummary section might occur many times. The DailySummary section might include the temperature, the barometric pressure, and the wind speed. The following code is an example of a weather report:

<WeatherReport>
  <DailySummary>
    <Temperature>20</Temperature>
    <Pressure>80</Pressure>
    <WindSpeed>10</WindSpeed>
  </DailySummary>
  <DailySummary>
    <Temperature>23</Temperature>
    <Pressure>78</Pressure>
    <WindSpeed>20</WindSpeed>
  </DailySummary>
  <DailySummary>
    <Temperature>24</Temperature>
    <Pressure>77</Pressure>
    <WindSpeed>16</WindSpeed>
  </DailySummary>
</WeatherReport>

The following illustration shows this weather report displayed in BizTalk Editor.

Weather report specification

In the previous code, the Maximum Occurrences property (which would appear on the Reference tab) for the DailySummary record is set at an asterisk (*). This indicates that the DailySummary record loops, and BizTalk Mapper compiles this record as a loop.

You might want to collect weather information for the first two DailySummary records of the weather report. In BizTalk Mapper, each field from the DailySummary record of the incoming source specification can be connected to an Index functoid, and each Index functoid can specify from which DailySummary record to draw the information: the first or the second. The Index functoids can then be connected to the appropriate fields of a destination specification.

The following illustration shows Index functoids used in this way.

Weather Report map

To get the daily summary information for the first day, the top three Index functoids would have to have an index value of 1. To get the daily summary information for the second day, the last three Index functoids would have to have an index value of 2.

Index sequence inputs are set as input parameters on the General tab of the property sheet of an Index functoid. Double-click an Index functoid to display its property sheet. The first input parameter identifies the field in the source specification that links into the Index functoid. The succeeding input parameter or parameters indicate index values.

The following illustration shows the property sheet for the top Index functoid in the previous map.

Index functoid properties

Notes

  • An Index functoid input parameter assigned any non-numeric constant value is interpreted by BizTalk Mapper to have a value of 1. For example, in the previous illustration, if the second input parameter were replaced with an input parameter with a value of "anystring", the mapping result would be unchanged.

  • Although index sequence input is typically a constant value on the General tab of the Functoid Properties dialog box, it is possible to use a link from a node in the source specification for the input sequence value. If this link comes from a looping record that is not a parent of the first input parameter, the index sequence input value comes from the first instance of the node in the incoming document.

  • The value of the index sequence input is always in relation to the current context in the source document.

If you had multiple weather reports in the same input file, and each weather report had multiple daily summaries, you might need to specify more than one index value. The following code is an example of an input file with multiple weather reports:

<WeatherReports>
  <WeatherReport1>
    <DailySummary>
      <Temperature>20</Temperature>
      <Pressure>80</Pressure>
      <WindSpeed>10</WindSpeed>
    </DailySummary>
    <DailySummary>
      <Temperature>23</Temperature>
      <Pressure>78</Pressure>
      <WindSpeed>20</WindSpeed>
    </DailySummary>
  </WeatherReport1>
  <WeatherReport2>
    <DailySummary>
      <Temperature>24</Temperature>
      <Pressure>77</Pressure>
      <WindSpeed>16</WindSpeed>
    </DailySummary>
    <DailySummary>
      <Temperature>22</Temperature>
      <Pressure>79</Pressure>
      <WindSpeed>21</WindSpeed>
    </DailySummary>
  </WeatherReport2>
</WeatherReports>

An Index functoid with two index values, the first set at 1 and the second set at 2, gets a field value from the first daily summary of the second weather report.

Important

  • An Index functoid must have as many index values as there are parent nodes from the field level to the first level below the root node. For example, in the multiple weather report sample document, two index values are required. In the single weather report sample document, only one index value is required. Failure to set the required number of index values of an Index functoid creates output based on the first node in the source document that matches the first input parameter of the Index functoid.

Related Topic

Advanced Functoids


Using the Iteration Functoid

The Iteration functoid identifies which sequence number in a looping record is being mapped at any given time. The following illustration shows the Iteration functoid used in conjunction with an Equal functoid.

Iteration functoid map

There is a pair of functoids (the Iteration functoid Iteration functoid and the Equal functoid Equal functoid ) for each of the two records in the destination specification. The following illustration shows the property sheet for the top Equal functoid.

Top Conditional functoid property sheet

The following code is an example of an incoming document instance that conforms to the structure of the source specification:

<Root>
<Record1 Field1="A"/>
<Record1 Field1="B"/>
</Root>

As the source specification loops through the incoming document instance, the Iteration functoid returns the value 1 while the first record is being mapped and the value 2 while the second record is being mapped. The Equal functoid returns the value "true" when its two input parameters are equal. Therefore, the top functoid pair returns the value "true" while the first record of the incoming document instance is being mapped. The value "true" is passed to Record2 of the destination specification, and Record2 is written to the output document. If the second input parameter of the bottom Equal functoid has a value of 2, the bottom functoid pair behaves in a manner similar to the top functoid pair. In other words, when the second record of the incoming document instance is mapped, Record3 of the destination specification is written to the output document instance. The following code shows the output document instance:

<Root2>
<Record2 Field2="A"/>
<Record3 Field3="B"/>
</Root2>

Related Topic

Advanced Functoids


Using the Value Mapping Functoid

The Value Mapping functoid Value Mapping functoid requires two input parameters, and returns the value of the second input parameter if the value of the first parameter is "true". The following illustration shows a map with the Value Mapping functoid used in this way.

To complete the map, you must set the input parameters for each functoid. The following illustration shows the property sheet for each of the three Value Mapping functoids.

Value Mapping functoid property sheet

The following illustration shows the property sheet for the top Equal functoid.

Equal functoid property sheet

The middle Equal functoid property sheet is similar, but its second input parameter has a constant value of Y. The bottom Equal functoid property sheet is also similar, but its second input parameter has a constant value of Z.

The following code is an example of a document instance that corresponds to the source specification of the map:

<Root>
  <Record1>
    <Record2 Name="X" Value="1"/>
    <Record2 Name="Y" Value="2"/>
    <Record2 Name="Z" Value="3"/>
  </Record1>
  <Record>
    <Record2 Name="X" Value="4"/>
    <Record2 Name="Y" Value="5"/>
    <Record2 Name="Z" Value="6"/>
  </Record>
  <Record1>
    <Record2 Name="X" Value="7"/>
    <Record2 Name="Y" Value="8"/>
    <Record2 Name="Z" Value="9"/>
  </Record1>
</Root>

A Name value of X makes the top Equal functoid of the map return a value of "true". The "true" value returned by the Equal functoid makes the Attribute Value functoid that it is linked to return a value of 1.

Using this map and this source document instance, BizTalk Server outputs the following document instance:

<Root>
<Record X="1"/>
<Record Y="2"/>
<Record Z="3"/>
<Record X="4"/>
<Record Y="5"/>
<Record Z="6"/>
<Record X="7"/>
<Record Y="8"/>
<Record Z="9"/>
</Root>

Important

  • The Value Mapping functoid accepts Boolean input only in the form of the lowercase strings "true" and "false". For example, if a field in an incoming document instance has a value of "True" and is linked directly to the top input parameter of a Value Mapping functoid, the value of the second input parameter of the Value Mapping functoid is not passed to the output document.

Related Topic

Advanced Functoids

Using the Value Mapping (Flattening) Functoid


Using the Value Mapping (Flattening) Functoid

A common scenario for users of Microsoft Commerce Server is to map from a Commerce Server catalog to a flat schema. The Value Mapping (Flattening) functoid makes this type of map possible. The following code is an example of a Commerce Server catalog:

<Root>
  <Record1>
    <Record2 Name="X" Value="1"/>
    <Record2 Name="Y" Value="2"/>
    <Record2 Name="Z" Value="3"/>
  </Record1>
  <Record1>
    <Record2 Name="X" Value="4"/>
    <Record2 Name="Y" Value="5"/>
    <Record2 Name="Z" Value="6"/>
  </Record1>
  <Record1>
    <Record2 Name="X" Value="7"/>
    <Record2 Name="Y" Value="8"/>
    <Record2 Name="Z" Value="9"/>
  </Record1>
</Root>

The following code is an example of a flat schema:

<Root>
  <Record X="1" Y="2" Z="3"/>
  <Record X="4" Y="5" Z="6"/>
  <Record X="7" Y="8" Z="9"/>
</Root>

In this mapping scenario it is important to maintain the one-to-one correspondence between the three records in the catalog and the three records in the flat schema. The following illustration shows a map that maintains this correspondence.

Value Mapping functoid

In this map, the source specification represents the structure of the incoming catalog, and the destination specification represents the structure of the outgoing flat schema. There is a pair of functoids (the Equal functoid Equal functoid and the Value Mapping (Flattening) functoid Value Mapping (Flattening) functoid) for each of the three records. The following illustration shows the property sheet for each of the three Value Mapping (Flattening) functoids.

Value Mapping functoid property sheet

The following illustration shows the property sheet for the top Equal functoid.

Equal functoid property sheet

The middle Equal functoid property sheet is similar, but its second input parameter has a constant value of Y. The bottom Equal functoid property sheet is also similar, but its second input parameter has a constant value of Z.

The top functoid pair works together to ensure that the value of X is passed from each of the three records in the catalog to each of the three records in the flat schema. The Value Mapping (Flattening) functoid returns the value of the second parameter of its property sheet only if the value of the first parameter is "true". For this reason, the top Value Mapping (Flattening) functoid returns the value of /Root/Record/Field/@Value only if the Equal functoid it is linked to returns a value of "true". The Equal functoid to which it is linked returns a value of "true" only for fields in the incoming catalog with Name values of X.

The Equal functoid of the middle functoid pair returns a value of "true" only for fields in the incoming specification with Name values of Y, so this pair of functoids ensures that the value of Y is passed from each of the three records in the catalog to each of the three records in the flat schema. The third functoid pair handles the value of Z in a similar manner.

Important

  • The Value Mapping (Flattening) functoid accepts Boolean input only in the form of the lowercase strings "true" and "false". For example, if a field in an incoming document instance has the value "True" and is linked directly to the top input parameter of a Value Mapping (Flattening) functoid, the value of the second input parameter of the Value Mapping (Flattening) functoid is not passed to the output document.

Note

  • If a record in an incoming catalog document instance has more than one field with an attribute that matches the second input parameter of one of the Equal functoids in this mapping scenario, only the last record with this match is mapped to the output document. For example, in the previous example of a Commerce Server catalog, if there were three Field elements in the first Record element that had Name attributes with values of X, only the last Field element would map.

For information about mapping from a flat schema to a Commerce Server catalog (mapping in the opposite direction from the previous mapping scenario), see Using the Looping Functoid.

Related Topics

Advanced Functoids

Using the Value Mapping Functoid


Using the Looping Functoid

The Looping functoid Looping functoid is used to combine multiple records and/or fields in the source specification into a single record in the destination specification. For each loop represented as loop from a node in the Source Specification tree to the Looping functoid, BizTalk Mapper traverses backward from the Destination Specification tree node to the Source Specification tree node for each child link and generates the appropriate Extensible Stylesheet Language (XSL) Transformation (XSLT). However, if there is a link to a Source Specification node, which has a parent of another input source link (from a node in the Source Specification tree to the Looping functoid), the Destination Specification node will not be created.

The following illustration shows the Looping functoid used in this way.

Looping functoid map

The BillTo record of the Source Specification tree and the Addresses record of the Destination Specification loop, as indicated by the Maximum Occurrences setting of * on the Source Attributes and Destination Attributes sections of the Properties tab. In this example, the Header record of the Source Specification also loops. If an incoming document instance had three BillTo records and two ShipTo records, the Looping functoid would combine these to create five Addresses records in the outgoing document.

The following code is a sample incoming document instance:

<Root>
<BillTo Name="Karin Zimprich" Address="345 North 63rd Street"
City="Boston" PostalCode="07458"></BillTo>
<BillTo Name="Wendy Wheeler" Address="7890 Broadway"
City="Columbus" PostalCode="46290"></BillTo>
<BillTo Name="Florian Voss" Address="1234 Main Street"
City="Denver" PostalCode="97402"></BillTo>
<ShipTo Name="Kelly Focht" Address="456 First Avenue"
City="Miami" PostalCode="81406"></ShipTo>
<ShipTo Name="Jim Kim" Address="567 2nd Avenue"
City="Seattle" PostalCode="98103"></ShipTo>
<Header ID="01"></Header>
<Header ID="02"></Header>
<Header ID="03"></Header>
</Root>

This incoming document instance would produce the following outgoing document instance when processed by the map shown in the previous illustration:

<Root>
<Addresses Name="Karin Zimprich" Address="345 North 63rd Street"
City="Boston" PostalCode="07458" ID="01" />
<Addresses Name="Wendy Wheeler" Address="7890 Broadway"
City="Columbus" PostalCode="46290" ID="01" />
<Addresses Name="Florian Voss" Address="1234 Main Street"
City="Denver" PostalCode="97402" ID="01" />
<Addresses Name="Kelly Focht" Address="456 First Avenue"
City="Miami" PostalCode="81406" ID="01" />
<Addresses Name="Jim Kim" Address="567 2nd Avenue"
City="Seattle" PostalCode="98103" ID="01" />
</Root>

Notice that in each Addresses record created in the outgoing document instance, the value of the ID field is "01". This is because the Header record is not connected to the Looping functoid. The first ID field value of the incoming document instance is passed to each record created in the outgoing document instance.

Important

  • Under certain conditions, some functoids might not behave as expected when they are used in a map with a Looping functoid. If a functoid meets the following condition, it does not produce the expected results:
    • Two or more of the functoid's source specification links are linked to child fields of the Looping functoid's input records. The child fields are not siblings.

    If you were to add a functoid that met these conditions to the previous map, the functoid might have one source specification link connected to the Name field under the BillTo record, another source specification link connected to the Name field under the ShipTo record, and a destination specification link connected to the Name field under the Addresses record.

Conditional looping

Conditional looping can be achieved by attaching the output of a looping functoid and a logical functoid to the same destination record. The destination records will be created only when the logical condition is met.

In the previous illustration, the first logical functoid compares the NName field under BillTo to "Cynthia Randall" and creates the destination Addresses record only if that condition is met. The second logical functoid compares the Name field under ShipTo to "Jay Adams" and creates the destination Addresses record only if that condition is met. Given the same source data in the looping functoid example the output for this example would be:

<Root>
<Addresses Name="Cynthia Randall" Address="345 ABC Street" City="Boston" PostalCode="70000" ID="01" />
<Addresses Name="Jay Adams" Address="567 ABC Avenue" City="Seattle" PostalCode="98000" ID="01" /> </Root>
</Root>

Flat schema to Commerce Server catalog

You can use the Looping functoid to map a flat schema to a Microsoft Commerce Server catalog. For more information about flat schemas and Commerce Server catalogs, see Using the Value Mapping (Flattening) Functoid.

The following illustration shows a flat schema mapped to a Commerce Server catalog.

Flat file to catalog map

Important

  • For this type of map to work correctly, you must do the following:
    • For each link that connects to the Name field in the destination specification, set the source-specification link properties to copy the name. For more information, see Select compiler properties for source-specification links.

    • For each link that connects to the Value field in the destination specification, set the source-specification link properties to copy the value. For more information, see Select compiler properties for source-specification links.

    • For the link that connects the Looping functoid to the record named Record1 in the destination specification, set destination-specification link properties to match links top-down. For more information, see Select compiler properties for destination-specification links.

    • Ensure that Allow multiple inputs to destination tree nodes is selected in the BizTalk Mapper Options dialog box. For more information, see BizTalk Mapper Options: General Tab.

Related Topics

Select compiler properties for destination-specification links

Select compiler properties for source-specification links

Using the Value Mapping (Flattening) Functoid


Integrating BizTalk Services Using Maps

When you integrate BizTalk Orchestration Services and BizTalk Messaging Services using a non-HTTP transport, you might need to create a map to convert a path name to a format name. For more information, see Integrating BizTalk Services.

Converting a path name to a format name

The following code is an example of a message queue path name:

private$\sourcechannel2{9e0016bf-be1f-48fe-82de-b27077ab5e73}

To convert this path name to a format name, you need to add the following string to the beginning of the path name:

queue://Direct=OS:

You can do this with the Concatenate functoid.

The following illustration shows a map that uses the Concatenate functoid, which concatenates two or more strings. For more information about the Concatenate functoid, see String Functoids.

Path name to format name

Double-clicking the Concatenate functoid displays its properties. The following illustration shows how the properties should look for a Concatenate functoid in a map that adds the queue://Direct=OS: prefix to the private$\sourcechannel2{9e0016bf-be1f-48fe-82de-b27077ab5e73} path name.

For more information, see Edit Functoid Properties.

Concatenate functoid properties


Compiling Maps

When you compile maps, the BizTalk Mapper compiler component generates an Extensible Stylesheet Language (XSL) style sheet. This process creates a compiled map that can transform an instance document of the source schema to an instance document of the destination schema. Compiling a map enforces the structural rules and transformations that are specified in the mapping grid.

Transformations, such as links, are processed in the same order that records and fields appear in the instance of the destination structure. For example, when BizTalk Mapper reaches a destination record or field that has a link associated with it, BizTalk Mapper compiles the properties of the link. The action might be a simple copy value from a record or field in the source specification, or the action might calculate values from one or more records and fields from the source to one or more records and fields in the destination, based on the properties of a functoid.

BizTalk Mapper generates a warning on the Warnings tab when the compiler encounters a situation that might yield incorrect output. For example, if a functoid that requires one input parameter has no input parameters, BizTalk Mapper generates a warning on the Warnings tab when the map is compiled. It is recommended that you do not use a map in a production environment until it is no longer generating warnings.

The compiled map is used by BizTalk Server to perform the actual translation of an input instance to an output instance.

The following topic is covered in this section:

  • Compiler Directives

Related Topic

Matching Node-Hierarchy Levels


Compiler Directives

When mapping from an element, typical Extensible Stylesheet Language (XSL) Transformation (XSLT) looks like:

<xsl:attribute name='CatalogPurposeCode'>
<xsl:value-of select='BCT/BCT01/text()'/>
</xsl:attribute>

If BCT01 contains mixed content, the use of "text()" makes it possible to access the first text only up to the point of the first sub-element. If "text()" were not used in this XSLT statement, the result would be that all text content, plus any text content of sub-elements, would be mapped as one string of text. However, BizTalk Mapper provides a feature that enables you to control the copying of values of nodes in the Source Specification tree.

By right-clicking a link that is connected to a node in the Source Specification tree and selecting Properties, you can specify how you want BizTalk Mapper to handle the transformation of data. The following choices are available:

  • Copy text value (default). Copies the value of the node in the incoming document instance. For example, <Node>Hello<Name>Chris</Name>Cannon</Node> would result in "Hello."

  • Copy text and sub-content value. Copies the concatenated value of the node and all values of descendants of it in the incoming document instance. For example, <Node>Hello<Name>Chris</Name>Cannon</Node> would result in "HelloChrisCannon."

  • Copy name. Copies the name of the node in the incoming document instance.

You can also handle how hierarchies are handled in BizTalk Mapper by right-clicking a link that is connected to a node in the Destination Specification tree and selecting Properties. For more information about these compiler directives, see Matching Node-Hierarchy Levels.

Related Topics

Select compiler properties for destination-specification links

Select compiler properties for source-specification links


Testing Maps

As you create a map, you can use BizTalk Mapper to verify that the map you designed produces the correct output. The Test Map feature (an option on the Tools menu) automatically generates a test instance of the source document from the specification. This feature uses information from the source specification, such as the number of occurrences of records and the data types of fields, from the specification and generates the test instance. You can specify a value for any record or field in the Source test value box on the Values tab and test the results of that data.

BizTalk Mapper supports instances as native or Extensible Markup Language (XML). In addition, it also supports native output from the map test process where applicable. Depending on the source specification and destination specification that make up your map, one or more of the options in the following table will be available for you to test your map.

Test Map option | Description
Generated XML to XML | A test instance of the source document is built and then fed to the style sheet. The output is displayed in the Output window as XML.
Generated XML to Native | A test instance of the source document is built and then fed to the style sheet. The output is serialized to native format and displayed in the Output window as native data. This option is not available if the output schema is XML.
Instance XML to XML | An instance file that you specify is used to create the output, which is displayed in the Output window as XML.
Instance XML to Native | An instance file that you specify is used to create the output, which is displayed in the Output window as native data. This option is not available if the output schema is XML.
Native Instance to XML | A native instance file that you specify is used to create the output, which is displayed in the Output window as XML. The format of the specified instance is assumed to be the same as the standard for the input schema. This option is not available if the input schema is XML.
Native Instance to Native | A native instance file that you specify is used to create the output, which is displayed in the Output window as native data. The format of the specified instance is assumed to be the same as the standard for the input schema. This option is not available if the input schema or output schema is XML.

When you test a map, BizTalk Mapper automatically compiles it. However, it is best to first compile a map and resolve any warnings or errors prior to testing it. Before the test begins you are prompted to save your file. Saving your file prior to testing it is a precautionary measure to preserve your data in case any problems are accidentally introduced into the map.

BizTalk Mapper gives you the option to validate source instance data against the source specification prior to map testing. If one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XML-Data Reduced (XDR) file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.

BizTalk Mapper also gives you the option to validate content after the mapping functionality has been completed. In this case, BizTalk Mapper will validate the output data against the destination specification. As is the case with Validate content before map test functionality, if one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XDR file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.

After you test a map, the results appear on the Output tab. The test data corresponds to the destination specification.

The following topic is covered in this section:

  • Setting Document Delimiters

Related Topics

BizTalk Mapper Options: Document Delimiters Tab

BizTalk Mapper Options: General Tab

Test maps

Test record and field properties that have links


Setting Document Delimiters

BizTalk Mapper enables you to specify delimiters during map testing. You can use the Document Delimiters tab to specify default delimiters to use during testing and can also specify whether or not to automatically display the Document Delimiters dialog box each time you test a map. You can specify unique delimiters for records and fields in the Source Specification tree and unique delimiters for records and fields in the Destination Specification tree. You can set delimiters once or have BizTalk Mapper prompt you during each test for specific delimiters.

The following table lists the default values for delimiters.

Delimiter | Value
Record delimiter | ~ (0x7e)
Field delimiter | * (0x2a)
Subfield delimiter | > (0x3e)
Escape | ? (0x3f)


Why Perform BizTalk Mapper Tasks

This section provides a quick reference about why you perform BizTalk Mapper tasks. The following table identifies primary tasks and their specific subtasks, lists the purpose of each task, and provides links to the corresponding procedures.

Task Why perform the task
Change BizTalk Mapper Options:
  • BizTalk Mapper Options: General Tab
 To customize the behavior of BizTalk Mapper with regard to:
  • Receiving warnings

  • Viewing and clearing compiler links

  • Allowing record content links

  • Allowing multiple inputs into the Destination Specification tree

  • Saving content

  • Validating content
  • BizTalk Mapper Options: Colors Tab
 To customize the colors on the mapping grid.
  • BizTalk Mapper Options: Document Delimiters
 If you have a delimited structure for a specification, then you must set document delimiters for instance testing. Document delimiters are necessary for Microsoft BizTalk Server 2002 to process data in a production environment.
  • BizTalk Mapper Options: XSLT output
 To omit or include an XML declaration when the data is output.
Create, Open, and Save Maps:
  • Create new maps
 To enable the process of data transformation from one source to another, using links and functoids.
  • Open maps from a local hard drive
 If you want to work on a local copy of a map. For example, you might want to make some modifications and then test the map without impacting the collaborative copy that is stored in Web Distributed Authoring and Versioning (WebDAV).
  • Retrieve maps from WebDAV
 If you need to work on the collaborative copy of a map that others can also access and modify. This is the file that BizTalk Messaging Manager uses when processing transactions.
  • Open existing maps from a folder
 If you want to work on a local copy of a map. For example, you might want to make some modifications and then test the map without impacting the collaborative copy that is stored in WebDAV.
  • Save new maps
 If you want to save a local copy of a map that you just created. For example, you might want to save a map that you just created without impacting the collaborative copy that is stored in WebDAV.
  • Save existing maps
 If you want to save a local copy of a map that you modified. For example, you might want to save a map that you have modified without impacting the collaborative copy that is stored in WebDAV.
  • Save compiled maps
 To create a map that BizTalk Server can use to perform the actual translation of an input instance to an output instance at run time. The compiling process stores all information about the source specifications and destination specifications, including all content and functionality of links and objects.
  • Store maps
 If you need to make a map available to BizTalk Messaging Manager through WebDAV. This will also make the file available to others to use.
Replace Specifications:
  • Replace source specifications
 It is likely that when you create a map, the source specification may undergo further modification, such as adding additional records or fields. This feature enables you to replace the source specification and maintain all, or nearly all the links and functoids you have created in your map between the source specification and destination specification.
  • Replace destination specifications
 It is likely that when you create a map, the destination specification may undergo further modification, such as adding additional records or fields. This feature enables you to replace the destination specification and maintain all, or nearly all the links and functoids you have created in your map between the source specification and destination specification.
Work with Grid Pages:
  • Add grid pages
 If you want to simplify the view of your map. For example, if you add a grid page, you can put all the links and functoids that relate to header information on one page and links and functoids that relate to the body of your map on another page. You can also rename and delete grid pages that you have created.
Add and Work with Functoids:
  • Add string functoids
 To manipulate data strings. For example, the String Find functoid finds one text string within another text string, and returns the position of the first character of the found string.
  • Add mathematical functoids
 To perform calculations by using specific values, called arguments, in a particular order or structure. For example, the Addition functoid adds the values of the designated fields or records.
  • Add logical functoids
 To perform specific logical tests. For example, if a logical functoid is connected to a record in the destination specification and returns the value "true", the corresponding record in the output document is generated. If a logical functoid is connected to a record in the destination specification and returns the value "false", the corresponding record in the output document is not generated.

You might also need to add a logical functoid to serve as an input value for other functoids in a map.

  • Add date and time functoids
 To manipulate date and time data or add current date, time, or date and time data to a record or field in the destination specification.
  • Add conversion functoids
 To convert data. For example, these functoids can be used to convert a character to its ASCII value or a value to the corresponding ASCII character. Conversion functoids closely match engineering functions such as DEC2HEX, which returns a hexadecimal value when given a decimal value.
  • Add scientific functoids
 To convert a numeric value to a scientific value. For example, the Cosine functoid takes a value in radians from a field or record and returns the value of the cosine.
  • Add cumulative functoids
 To return the sum, average, or minimum or maximum input of a looping record.
  • Add database functoids
 To handle the transformation of coded data to uncoded data. For example, one company might use a code to represent a store name and address. And their trading partner needs to know the actual store name and address to process a transaction. Using a database functoid allows BizTalk Server to look up a code in a database and replace the code with the actual value of the code.
  • Add the Scripting functoid
 To use custom Microsoft Visual Basic script or Microsoft JScript for performing custom operations not possible with the functoids available on the functoid palette.
  • Add the Record Count functoid
 To determine the total number of items related to a looping record.

For example, a Record Count functoid might be used to count the number of items that exist in an incoming purchase order and output that value to a field in the outgoing invoice.
  • Add the Index functoid
 To access a specific occurrence of a record that repeats. For example, if you have a PO line item that repeats six times and only want to get the value from the third occurrence, you would use the Index functoid.
  • Add the Iteration functoid
 To identify which sequence number in a looping record is being mapped at any given time.
  • Add the Value Mapping functoid
 To move data that meets a logical requirement, such as "true" or "false".
  • Add the Value Mapping (Flattening) functoid
 To move data that meets a logical requirement, such as "true" or "false". This is similar to the Add the Value Mapping functoid, but in this case the hierarchy is flattened. This means that if something repeats three times in the Source Specification tree, only one occurrence will be created in the Destination Specification tree.
  • Add the Looping functoid
 To force the compiler to loop the Destination Specification tree data according to the looping behavior of the Source Specification tree data. This is called parallel looping behavior, which is typically explicit and should happen automatically. However in some complex maps, you may need to use a Looping functoid to force this behavior.
  • Move functoids and links, or links, between grid pages
 To simplify the complexity of the grid page, which can become quite complex with numerous links and functoids.
  • Information about Functoid Parameters
 To clearly understand the parameter requirements for each functoid.
  • Input Parameters
 To set parameters, such as a constant value, for a functoid. You can also rename input parameters, or move them up and down (for situations in which the order of parameters matters) to change when BizTalk Mapper processes the parameter.
Add and Work with Links:
  • Create links between fields
 To copy data from a field in the Source Specification tree to a field in the Destination Specification tree.
  • Create links between fields and functoids
 To copy data from a field in the Source Specification tree to a functoid, which is required for further manipulation, prior to being output to the Destination Specification tree.
  • Create links between records and fields
 To copy data from a record in the Source Specification tree to a field in the Destination Specification tree.

Important

  • To perform this task, you must select the Allow record content links in the BizTalk Mapper Options dialog box.
  • Create links between records and functoids
 To copy data from a record in the Source Specification tree to a functoid, which is required for further manipulation, prior to being output to the Destination Specification tree.

Important

  • To perform this task, you must select the Allow record content links in the BizTalk Mapper Options dialog box.
  • Create links between functoids
 To accomplish tasks in which multiple functoids are required to generate the right output to the Destination Specification tree.
  • Allow record content links
 To enable you to create links between records and fields or between records and functoids.
  • Redirect links
 If you have made a mistake while drawing a link and want to redraw one of the end point links.
  • View links and functoids in the mapping grid
 To scroll the grid area so that you can view any link or functoid that exists in the grid.
  • View links and functoids by using the grid preview
 To display a representation of where the functoids are located on the mapping grid.
  • View Link Properties: General Tab
 To view information about the source and destination of a link.
  • View Link Properties: Compiler Tab
 To view the set compiler properties for source-specification links and compiler properties for destination-specification links.
  • Select compiler properties for source-specification links
 To control the way the compiler traverses the output tree. For example, if you want it to copy text values, copy text and sub-content values, or copy names from the Source Specification tree.
  • Select compiler properties for destination-specification links
 To control the way the compiler traverses the output tree. For example, you can have it flatten links, match links from the top down, or match links from the bottom up. For more information, see Matching Node-Hierarchy Levels.
Create and Manage Compiled Maps:
  • Compile maps
 To compile a map that BizTalk Server can use to perform the actual translation of an input instance to an output instance at run time. The compiling process stores all information about the source and destination specifications, including all content and functionality of links and objects.
  • Resolve warnings and errors after compiling a map
 To locate the errors in your map and determine how to resolve them.
  • Add constant values
 To create test data for a field in the Source Specification tree or to add a run-time constant value to a field in the Destination Specification tree.
Perform Map Testing:
  • Test record and field properties that have links
 To verify that the links contained in your map produce the correct output.
  • Test maps
 To verify that the map you designed produces the correct output. For example, the number of occurrences of records, data types of fields, and so on, are verified. The process involves generating a test instance of the source document from the specification.
Manage Views, Customize the User Interface, and Use Shortcut Keys:
  • Expand tree items
 To view all the records and fields in a specification from the viewpoint of the root node record or simply the records and fields from the viewpoint of a single record.
  • Collapse tree items
 To view only the root node record and/or parent records.
  • View record and field properties
 To view the properties for a record or field that are associated with the Declaration, Reference, Parse, Namespace, Dictionary, or Code List tab in BizTalk Editor.
  • Adjust the pane size for the Source Specification tree
 To view more or less of the Source Specification tree or more or less of the mapping grid area.
  • Adjust the pane size for the Destination Specification tree
 To view more or less of the Destination Specification tree or more or less of the mapping grid area.
  • Adjust the size of the lower pane
 To view more or less of the content contained on the Properties, Values, Output or Warnings tab.
  • Change mapping grid colors
 To change the color of the Grid foreground area, which represents the dashed lines in the mapping grid, or to change the color of the Grid background, which represents the background color of the mapping grid.
  • Change the color of links
 To change the color of fixed, elastic, partial, and compiler links.
  • Change the color of selected objects
 To change the color of objects you select with the mouse pointer.
  • Change the color of compiler warnings
 To change the color of the records or fields that will be highlighted when a warning has been generated.
  • Restore default colors
 To set all the color options back to their original settings.
  • Change text size
 To increase or decrease the font size of text in BizTalk Mapper.
  • BizTalk Mapper Shortcut Keys
 To use shortcut keys, rather than a mouse, to accomplish tasks.


How to Perform BizTalk Mapper Tasks

This section provides task-specific information about how to map data from one specification to another. It is highly recommended that you review the About BizTalk Mapper section to fully understand links and functoids, as well as other mapping properties and functionality.

The following topics are covered in this section:

  • Change BizTalk Mapper Options

  • Create New Maps

  • Open Maps

  • Save, Store, and Close Maps

  • Replace Specifications

  • Work with Grid Pages

  • Manage Functoids

  • Manage Links

  • Create and Manage Compiled Maps

  • Perform Map Testing

  • Manage Views

  • Customize the User Interface

  • BizTalk Mapper Shortcut Keys


Change BizTalk Mapper Options

In the BizTalk Mapper Options dialog box, you can set general options and choose colors for the mapping grid.

  • To view the BizTalk Mapper Options dialog box, on the Tools menu, click Options.

    The General tab appears by default.

For information about how to use the BizTalk Mapper Options dialog box, see the following procedures:

  • BizTalk Mapper Options: General Tab

  • BizTalk Mapper Options: Colors Tab

  • BizTalk Mapper Options: Document Delimiters Tab

  • BizTalk Mapper Options: XSLT output Tab


BizTalk Mapper Options: General Tab

For information about how to access the BizTalk Mapper Options dialog box, see Change BizTalk Mapper Options.

The General tab provides eight options that enable you to customize the behavior of BizTalk Mapper:

  • Warnings for simple linking errors (selected by default). You receive a warning when you attempt to create a link between nodes whose data types do not match.

  • View compiler links (selected by default). Compiler links appear on a map after compiling.

  • Clear compiler links after user action (cleared by default). Compiler links disappear after taking any action in BizTalk Mapper.

  • Allow record content links (selected by default). Content links from records to functoids can be created.

    Note

    • Certain functoids have input and/or output that does not use record content and is therefore unaffected by Allow record content links. This input and output consists of the logical functoids (output), the Count functoid (input), the Iteration functoid (input), and the Looping functoid (input and output).
  • Allow multiple inputs to destination tree nodes (cleared by default). Two or more links can be made to a node in the Destination Specification tree.

  • Prompt to save before testing the map (selected by default). After you click Test Map on the Tools menu, BizTalk Mapper displays a dialog box that asks if you want to save changes in your map file.

  • Validate content before map test (cleared by default). Data will be validated against the Source Specification tree before the mapping functionality has been completed from the source specification to the destination specification.

    Note

    • If one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XML-Data Reduced (XDR) file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.
  • Validate content after map test (cleared by default). After the mapping functionality has been completed, BizTalk Mapper will validate data in the destination specification.

    Note

    • If one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XDR file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.

Related Topic

BizTalk Mapper Options: Colors Tab


BizTalk Mapper Options: Colors Tab

For information about how to access the BizTalk Mapper Options dialog box, see Change BizTalk Mapper Options.

The Colors tab provides options that enable you to customize the colors on the mapping grid. For information about these options, see the following procedures:

  • Change mapping grid colors

  • Change the color of links

  • Change the color of selected objects

  • Change the color of compiler warnings

  • Restore default colors

Related Topic

BizTalk Mapper Options: General Tab


BizTalk Mapper Options: Document Delimiters Tab

For information about how to access the BizTalk Mapper Options dialog box, see Change BizTalk Mapper Options.

The Document Delimiters tab provides options that enable you to test a map. You can specify unique delimiters for every test or set default delimiters and not be prompted for new ones during testing.

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Document Delimiters tab.

  3. In the Delimiter Type area, select either Source Delimiter or Target Delimiter.

  4. Select an option from the drop-down lists, or type your own, in the following boxes:
    • Record delimiter

    • Field delimiter

    • Subfield delimiter

    • Escape character

    Important

    • If you specify your own delimiters, use Unicode character values. For a list of valid characters, go to the Global codepages page on the Microsoft Global Software Development Web site (www.microsoft.com/globaldev/reference/wincp.asp). You can use ANSI character codes, provided they are the same as the Unicode character codes, except for having two leading zeros.
  5. If you do not want to display the Document Delimiters dialog box each time you validate a document instance, clear the Prompt for delimiters during instance test box.

Important

  • Null terminator (delimiter) is not supported. If you need this support, remove or add the null delimiter from or to a flat file before or after processing the file.

  • If you are prompted for delimiters during instance testing because the Prompt for delimiters during instance test box is selected, the delimiters you specify are used to test only that instance. The delimiters specified on the Document Delimiters tab remain the default delimiters.

  • If the Prompt for delimiters during instance test box is selected, and the instance you are testing is an EDI file with envelope information, the Document Delimiters dialog box will not appear because BizTalk Mapper will automatically detect the delimiter needed. BizTalk Mapper will display the Prompt for delimiters during instance test box if you have specified to have it displayed during instance testing and it cannot determine the delimiters to use.

Note

  • If the instance contains multiple documents and envelope information (header/trailer), only the first document will be validated against the document delimiters specified on the Document Delimiters tab.


BizTalk Mapper Options: XSLT output Tab

For information about how to access the BizTalk Mapper Options dialog box, see Change BizTalk Mapper Options.

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the XSLT output tab.

  3. In the Omit XML declaration box, from the drop-down list, select Yes to omit a declaration or No to include the declaration.

    Note

    • This represents whether an XML declaration is outputted or not. An XML declaration would appear (if you selected No) similar to:
      <?xml version="1.0" encoding="utf-8" ?
  4. Click OK.


Create New Maps

To create a map, you must specify both a source specification and a destination specification.

  1. On the File menu, click New.

    The Select Source Specification Type dialog box appears.

  2. Double-click one of the following:
    • Local Files, and go to step 3.

    • Templates, and go to step 4.

    • WebDAV Files, and go to step 3.
  3. Browse to the folder that contains the source specification that you want to open and go to step 5.

  4. Click EDIFACT, X12, or XML and click OK.

    If you select EDIFACT or X12, you must also select the version you want to use. Click the folder for the version you want to use, click OK, and then go to step 5.

    Important

    • When the X12 templates included with the BizTalk Server installation are used in BizTalk Mapper, you might encounter an error message similar to the following:

      The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

      The X12 templates use the implied decimal data type Nx. If the input data contains a decimal point, the output will not match the N custom data type (which means no decimal point) and will create invalid instances in the intermediate XML file. In this release of BizTalk Server, the serializer might not detect whether the intermediate XML file contains a decimal point for data type N output. To resolve this issue, you must manually change the implied decimal data type in the X12 templates to any other numeric data type.

  5. Select the source specification and click Open or OK as appropriate.

    The Select Destination Specification Type dialog box appears.

  6. Double-click one of the following:
    • Local Files, and go to step 7.

    • Templates, and go to step 8.

    • WebDAV Files, and go to step 7.
  7. Browse to the folder that contains the destination specification that you want to open and go to step 9.

  8. Click EDIFACT, X12, or XML and click OK.

    If you select EDIFACT or X12, you must also select the version you want to use. Click the folder for the version you want to use, click OK, and then go to step 9.

  9. Select the destination specification and click Open or OK as appropriate.

  10. If you have selected an XDR schema, the Select Root Element dialog box might appear. If it does, select a root element from the Root elements list and click OK.

    Notes

    • If the XML-Data Reduced (XDR) schema does not contain a root, you must specify one from the possible nodes in the schema.

    • When you open a non-BizTalk Server XDR schema in BizTalk Mapper, you will see error and/or warning messages if element groups and/or namespaces are present in the schema. As a result, the map might not appear as you would expect.

    • Groups are not visually represented in the Source Specification tree or Destination Specification tree. If your map contains schemas that have groups, the run-time engine will validate against the group attribute, but BizTalk Mapper will not graphically depict any grouping reference.

Related Topics

Replace destination specifications

Replace source specifications


Open Maps

The following procedures are covered in this section:

  • Open maps from a local hard drive

  • Retrieve maps from WebDAV

  • Open existing maps from a folder


Open maps from a local hard drive

  1. On the File menu, click Open.

    The Open Map Source dialog box appears.

  2. Browse to the folder that contains a map you want to open.

  3. Click a map in the list and click Open.

Important

  • When the X12 templates included with the BizTalk Server installation are used in BizTalk Mapper, you might encounter an error message similar to the following:

    The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

    The X12 templates use the implied decimal data type Nx. If the input data contains a decimal point, the output will not match the N custom data type (which means no decimal point) and will create invalid instances in the intermediate XML file. In this release of BizTalk Server, the serializer might not detect whether the intermediate XML file contains a decimal point for data type N output. To resolve this issue, you must manually change the implied decimal data type in the X12 templates to any other numeric data type.

Note

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Retrieve maps from WebDAV


Retrieve maps from WebDAV

  1. On the File menu, click Retrieve from WebDAV.

    The Retrieve from WebDAV dialog box appears.

  2. In the Server list, click a server name.

    Important

    • If your Proxy Server Port is not 80, you will need to type the following in the Server list, http://<server name>:<port number>, to access maps stored in WebDAV.

    • You cannot retrieve maps on a secure server. For example, if the server is https://<server name>/biztalkserverrepository, you will not be able to access any maps.
  3. Browse to the folder that contains the map you want to retrieve, click the map, and then click Open.

Important

  • If you get an error message, such as "No BizTalk Server Repository was found on http://<server name>/BizTalkServerRepository/Maps," when you are trying to opening existing maps from WebDAV, re-register msdaipp.dll and then restart your computer. For more information about how to re-register msdaipp.dll, see Re-register msdaipp.dll to retrieve or store maps in WebDAV.

  • When the X12 templates included with the BizTalk Server installation are used in BizTalk Editor, you might encounter an error message similar to the following:

    The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

    The X12 templates use the implied decimal data type Nx. If the input data contains a decimal point, output will not match the N custom data type (which means no decimal point) and will create invalid instances in the intermediate XML file. In this release of BizTalk Server, the serializer might not detect whether the intermediate XML file contains a decimal point for data type N output. To resolve this issue, you must manually change the implied decimal data type in the X12 templates to any other numeric data type.

Notes

  • You might experience a delay the first time you connect to a remote WebDAV server.

  • To retrieve a map in WebDAV, you must have permission to retrieve files on the server.

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topics

Open maps from a local hard drive

Troubleshooting BizTalk Editor and BizTalk Mapper


Open existing maps from a folder

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.

  2. Locate the file you want to view in BizTalk Mapper.

    If necessary, click Restore Down to reduce the window size so that you can see the BizTalk Mapper window.

  3. Drag the file to BizTalk Mapper.

Important

  • When the X12 templates included with the BizTalk Server installation are used in BizTalk Editor, you might encounter an error message similar to the following:

    The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

    The X12 templates use the implied decimal data type Nx. If the input data contains a decimal point, output will not match the N custom data type (which means no decimal point) and will create invalid instances in the intermediate XML file. In this release of BizTalk Server, the serializer might not detect whether the intermediate XML file contains a decimal point for data type N output. To resolve this issue, you must manually change the implied decimal data type in the X12 templates to any other numeric data type.

Note

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.


Save, Store, and Close Maps

The following procedures are covered in this section:

  • Save new maps

  • Save existing maps

  • Save compiled maps

  • Store maps

  • Close maps


Save new maps

  1. On the File menu, click Save As.

    The Save Map Source As dialog box appears.

  2. In the File name box, type a name for the map.

  3. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to use a specification associated with ASCII characters, click UTF-8. For specifications associated with double-byte character sets, click Unicode.

Notes

  • When you save a map, BizTalk Mapper automatically compiles it. You can view the results of the compiled map on the Output tab.

  • When you save a map, BizTalk Mapper saves the map on your hard disk. To store a map in WebDAV, you must have permission to store files on the server.

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Store maps


Save existing maps

  • On the File menu, click Save.

Notes

  • When you save a map, BizTalk Mapper automatically compiles it. You can view the results of the compiled map on the Output tab.

  • When you save a map, BizTalk Mapper saves the map on your hard disk. To store a map in WebDAV, you must have permission to store files on the server.

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Store maps


Save compiled maps

  1. On the File menu, click Save Compiled Map As.

    The Save Compiled Map As dialog box appears.

    Note

    • This feature is only available if you have compiled a map.
  2. In the File name box, type a name for the file and click Save.

Note

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Store maps


Store maps

  1. On the File menu, click Store to WebDAV.

    The Store to WebDAV dialog box appears.

  2. In the Server list, click a server name.

    Important

    • If your Proxy Server Port is not 80, you will need to type the following in the Server list, http://<server name>:<port number>, to store maps in WebDAV.

    • You cannot store maps on a secure server. For example, if the server is https://<server name>/biztalkserverrepository, you will not be able to store any maps.
  3. Browse to the folder you want to use to store your map and, in the File name box, type the name of the file.

  4. In the Encoding list, click either UTF-8 or Unicode and click Save.

    If you want to use a specification associated with ASCII characters, click UTF-8. For specifications associated with double-byte character sets, click Unicode.

International Issues

  • Files can be saved only in Unicode encodings in the WebDAV repository. However, the WebDAV repository cannot store files with names in different code pages.

  • WebDAV does not support Unicode characters in file names.

  • Make sure that your system locale is set to your language. For example, international users who install the English version of BizTalk Server 2002 on a computer running the English version of Microsoft® Windows®, and want to name files with characters that are not supported in the Latin I code page (Windows 1252 including English), must change the system locale to their user locale.

  • You cannot store files with double-byte character set (DBCS) file names if your locale setting is incorrect. For more information, see ???.xml appears in the WebDAV dialog box.

Important

  • If you get an error message, such as "No BizTalk Server Repository was found on http://<server name>/BizTalkServerRepository/Maps," when you are trying to store maps to WebDAV, re-register msdaipp.dll and then restart your computer. For more information about how to re-register msdaipp.dll, see Re-register msdaipp.dll to retrieve or store files in WebDAV.

Notes

  • You might experience a delay the first time you connect to a remote WebDAV server.

  • To store a map in WebDAV, you must have permission to store files on the server.

  • Once you install BizTalk Server 2002, if you open a map that you created using BizTalk Server 2000, the file format will be changed if you save the file and you will not be able to open it again using BizTalk Server 2000.

Related Topic

Troubleshooting BizTalk Editor and BizTalk Mapper


Close maps

  • On the File menu, click Close.


Replace Specifications

The following procedures are covered in this section:

  • Replace source specifications

  • Replace destination specifications


Replace source specifications

  1. On the Edit menu, click Replace Source Specification.

    If you have not saved your map, you are prompted to save changes to the map source.

    The Select Source Specification Type dialog box appears.

  2. Double-click one of the following:
    • Local Files, and go to step 3.

    • Templates, and go to step 4.

    • WebDAV Files, and go to step 3.
  3. Browse to the folder that contains the source specification and go to step 5.

  4. Click EDIFACT, X12, or XML and click OK.

    If you select EDIFACT or X12, you must also select the version you want to use. Click the folder for the version you want, click OK, and then go to step 5.

  5. Select the source specification and click Open or OK as appropriate.

Notes

  • Source test values are preserved when you replace a source specification, provided that the fields associated with these values exist in the new specification.

  • The Warnings tab lists all warnings related to links that might break as a result of replacing the source specification. If a warning appears, the problem might exist over several grid pages.

    For example, if you have grid page 1 with a record (named Item) in the Source Specification tree linked to a record (named Number) in the Destination Specification tree, and on grid page 2 you have a record (named Product) in the Source Specification tree linked to the same Number record in the Destination Specification tree, a warning message will be generated stating that you have multiple inputs to the same record. However if you view grid page 1, you will see only one input into the Number record.

Related Topic

Replace destination specifications


Replace destination specifications

  1. On the Edit menu, click Replace Destination Specification.

    If you have not saved your map, you are prompted to save changes to the map source.

    The Select Destination Specification Type dialog box appears.

  2. Double-click one of the following:
    • Local Files, and go to step 3.

    • Templates, and go to step 4.

    • WebDAV Files, and go to step 3.
  3. Browse to the folder that contains the destination specification and go to step 5.

  4. Click EDIFACT, X12, or XML and click OK.

    If you select EDIFACT or X12, you must also select the version you want to use. Click the folder for the version you want, click OK, and then go to step 5.

  5. Select the destination specification and click Open or OK as appropriate.

Notes

  • Destination constant values are preserved when you replace a destination specification, provided that the fields associated with these values exist in the new specification. For more information about destination constant values, see Add constant values.

  • The Warnings tab lists all warnings related to links that might break as a result of replacing the destination specification. If a warning appears, the problem might exist over several grid pages.

    For example, if you have grid page 1 with a record (named Item) in the Source Specification tree linked to a record (named Number) in the Destination Specification tree, and on grid page 2 you have a record (named Product) in the Source Specification tree linked to the same Number record in the Destination Specification tree, a warning message will be generated stating that you have multiple inputs to the same record. However if you view grid page 1, you will see only one input into the Number record.

Related Topics

Add constant values

Replace source specifications


Work with Grid Pages

The following procedures are covered in this section:

  • Add grid pages

  • Rename grid pages

  • Delete grid pages


Add grid pages

  • On the Edit menu, click Add Page.

Note

  • The maximum number of grid pages you can add is 20.


Rename grid pages

  • Double-click the grid page name, type a new name, and press ENTER.

Note

  • The auto-complete feature will automatically display a list of previous matching entries as you type.


Delete grid pages

  • On the Edit menu, click Delete Page.

Note

  • You can delete all but one of the grid pages.


Manage Functoids

The following topics are covered in this section:

  • Work with Functoids

  • Information about Functoid Parameters

  • Edit Functoid Properties


Work with Functoids

The functoid palette contains the functoids available in BizTalk Mapper. You can find the functoid that you want in the functoid palette and drag it to the mapping grid. The various types of functoids are organized in tabs. You might need to click the right arrow or left arrow to see tabs that are hidden from view.

The following procedures are covered in this section:

  • Add string functoids

  • Add mathematical functoids

  • Add logical functoids

  • Add date and time functoids

  • Add conversion functoids

  • Add scientific functoids

  • Add cumulative functoids

  • Add database functoids

  • Add the Scripting functoid

  • Add the Record Count functoid

  • Add the Index functoid

  • Add the Iteration functoid

  • Add the Value Mapping functoid

  • Add the Value Mapping (Flattening) functoid

  • Add the Looping functoid

  • Move functoids and links, or links, between grid pages

  • Select multiple links and functoids

  • Delete functoids

Related Topics

BizTalk Mapper Functoid Palette

Understanding Functoids


Add string functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the String tab.

  3. Drag a string functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific string functoids, see String Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add mathematical functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Mathematical tab.

  3. Drag a mathematical functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific mathematical functoids, see Mathematical Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

International Issue

  • Many locales use a comma (,) as the decimal symbol. A number that uses a comma as the decimal symbol will fail validation using Microsoft XML (MSXML) Parser because MSXML expects a period (.) to be used as the decimal symbol. To resolve this issue, change the decimal symbol from a comma to a period in the system locale settings using the following procedure:
    1. On the Start menu, point to Settings and click Control Panel.

    2. Double-click Regional Options.

      The Regional Options console appears.

    3. Click the Numbers tab.

    4. In the Decimal symbol list box, type: .

    5. Click Apply and click OK.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add logical functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Logical tab.

  3. Drag a logical functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific logical functoids, see Logical Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record in the Destination Specification tree.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Notes

  • Logical functoids are case sensitive when comparing two strings. For example, "Abc" and "abc" are not equal. The exception to this rule is when logical functoids compare strings that represent the Boolean values TRUE and FALSE. For example, "True" and "true" are equal.

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add date and time functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Date/Time tab.

  3. Drag a date and time functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific date and time functoids, see Date and Time Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Notes

  • The Date, Time, and Date and Time functoids require only a link to a field or a record in the Destination Specification tree.

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add conversion functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Conversion tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag a conversion functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific conversion functoids, see Conversion Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add scientific functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Scientific tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag a scientific functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific scientific functoids, see Scientific Functoids.

  4. Drag a record or field from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

Important

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add cumulative functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Cumulative tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag a cumulative functoid from the Functoid Palette to the mapping grid.

    For detailed information about specific cumulative functoids, see Cumulative Functoids.

  4. Drag a field (with a parent record that is looping) from the Source Specification tree to the functoid in the mapping grid, and then drag the functoid to a record or field in the Destination Specification tree.

    For more information about looping records, see Using Cumulative Functoids.

Important

  • For information about the context of this procedure, see Using Cumulative Functoids.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add database functoids

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Database tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag a database functoid from the Functoid Palette to the mapping grid.

    For detailed information about database functoids, see Database Functoids.

Important

  • For information about how to use database functoids to extract information from a database, see Using Database Functoids.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Scripting functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Scripting functoid Scripting functoid to the mapping grid.

    For detailed information about the Scripting functoid, see Advanced Functoids.

  4. Double-click the Scripting functoid.

    The Functoid Properties dialog box appears.

  5. Click the Script tab.

  6. In the Script Language area, select either VBScript or JScript, type the script that you want in the Functoid script area, and then click OK.

  7. Drag a record or field from the Source Specification tree to the Scripting functoid in the mapping grid, and then drag the Scripting functoid to the record or field in the Destination Specification tree.

Important

  • If there are multiple functions within a Scripting functoid, the first function is the main or primary function. This function must have parameters set if there are links into the functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Manage Views


Add the Record Count functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Record Count functoid Record Count functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Record Count functoid, see Advanced Functoids.

  4. Drag a looping record from the Source Specification tree to the Record Count functoid in the mapping grid, and then drag the Record Count functoid to a field in the Destination Specification tree.

    For more information about looping records, see Using the Record Count Functoid.

Important

  • For information about the context of this procedure, see Using the Record Count Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Index functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Index functoid Index functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Index functoid, see Advanced Functoids.

  4. Drag a field (with a parent record that is looping) from the Source Specification tree to the Index functoid in the mapping grid, and then drag the Index functoid to a field in the Destination Specification tree.

    For more information about looping records, see Using the Index Functoid.

  5. Double-click the Index functoid to display its property sheet.

  6. Click the Insert New Parameter button Insert New Parameter button, type the index value, and then press ENTER.

  7. Repeat step 6 as necessary.

  8. Click OK.

Important

  • For information about the context of this procedure, see Using the Index Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Iteration functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Iteration functoid Iteration functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Iteration functoid, see Advanced Functoids.

Important

  • For information about how to use the Iteration functoid, see Using the Iteration Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Value Mapping functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Value Mapping functoid Value Mapping functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Value Mapping functoid, see Advanced Functoids.

Important

  • For information about how to use the Value Mapping functoid, see Using the Value Mapping Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Add the Value Mapping (Flattening) functoid

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Value Mapping (Flattening) functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Value Mapping (Flattening) functoid Value Mapping (Flattening) functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Value Mapping (Flattening) functoid, see Advanced Functoids.

Important

  • For information about how to use the Value Mapping (Flattening) functoid, see Using the Value Mapping (Flattening) Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Add the Value Mapping functoid

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Add the Looping functoid

  1. On the View menu, click Functoid Palette.

  2. On the Functoid Palette, click the Advanced tab.

    You might need to click the right arrow on the Functoid Palette to view the tab.

  3. Drag the Looping functoid Looping functoid from the Functoid Palette to the mapping grid.

    For detailed information about the Looping functoid, see Advanced Functoids.

Important

  • Under certain conditions, some functoids might not behave as expected when they are used in a map with a Looping functoid. If a functoid meets the following conditions, it does not produce the expected results:
    • The functoid has more than one source specification link.

    • Two or more of the functoid's source specification links are linked to child fields of the Looping functoid's input records. The child fields are not siblings.

    • The functoid has a destination specification link that is linked to a child field of the Looping functoid's output record.
  • For information about how to use the Looping functoid, see Using the Looping Functoid.

  • To create a link between a functoid and a record, you must enable the Allow record content links property. To do this, on the Tools menu, click Options. In the BizTalk Mapper Options dialog box, on the General tab, select the Allow record content links check box and click OK.

Note

  • You might need to expand the specification trees to see the records or fields that you want to map. For more information, see Expand tree items.

Related Topics

Allow record content links

Create links between fields and functoids

Create links between records and functoids

Understanding Functoids


Move functoids and links, or links, between grid pages

  1. Select the functoid or link you want to move.

    Notes

    • If you select a functoid, its associated links will also be selected and moved.

    • You cannot move a functoid unless all links and linked functoids within the chain are selected.
  2. If necessary, click the right arrow or left arrow to display the tab for the page where you want to place the functoid or link.

  3. Drag the functoid or link to the tab for the page you want to move it to and hold it over the tab until the grid page appears.

  4. Drag the functoid or link to the location on the grid where you want to place it.

Note

  • Before you move a functoid and its links from one page to another, all the links connected to it must be visible. To make the links visible, expand the source and destination nodes that contain the links connected to the functoid.


Select multiple links and functoids

  • Drag the cursor across the links and functoids that you want to select.


Delete functoids

  1. Right-click the functoid you want to remove and click Delete.

  2. Click Yes in the confirmation dialog box.


Information about Functoid Parameters

This section provides a description, an illustration, and the parameters for each functoid in Microsoft BizTalk Server 2002.

The following topics are covered in this section:

  • String Functoids

  • Mathematical Functoids

  • Logical Functoids

  • Date and Time Functoids

  • Conversion Functoids

  • Scientific Functoids

  • Cumulative Functoids

  • Database Functoids

  • Advanced Functoids


String Functoids

Functoid Parameters
String Find functoid String Find

Returns the position in a string at which another specified string begins.

 This functoid requires two input parameters. The first field that you link to the functoid is the string that determines the position of the second string.
String Left functoid String Left

Returns a specified number of characters from a text item, starting with the leftmost character.

 This functoid requires two input parameters. The first field that you link to the functoid is the string that determines the output string. The second field that you link to the functoid determines the number of characters returned as the output value. The result of the output is a string that is a subset of the first field that you linked to the functoid.
Lowercase functoid Lowercase

Converts a text item to lowercase characters.

 This functoid requires one input parameter.
String Right functoid String Right

Extracts a specified number of characters from a text item, starting with the rightmost character.

 This functoid requires two input parameters. The first field that you link to the functoid is the string that determines the output string. The second field that you link to the functoid determines the number of characters returned as the output value. The result of the output is a string that is a subset of the first field that you linked to the functoid.
String Length functoid String Length

Returns, as an integer, the size of an object, exclusive of any pad characters.

 This functoid requires one input parameter. The output value indicates the size, in characters, of the data contained in the input field.
String Extract functoid String Extract

Extracts a string specified by the start and end positions of an input string.

 This functoid requires three input parameters.

The order in which you link the fields to the functoid must adhere to the following criteria:

  1. String field

  2. Start position field

  3. End position field
Concatenate functoid Concatenate

Concatenates a series of input strings.

 This functoid can receive multiple input parameters.
String Left Trim functoid String Left Trim

Removes leading spaces from a text item.

 This functoid requires one input parameter.
String Right Trim functoid String Right Trim

Removes trailing spaces from a text item.

 This functoid requires one input parameter.
Uppercase functoid Uppercase

Converts a text item to uppercase characters.

 This functoid requires one input parameter.


Mathematical Functoids

Functoid | Parameters
Absolute Value functoid Absolute Value Returns the absolute value of a number. | This functoid requires one input parameter. The final value is always positive, regardless of the actual input value.
Integer functoid Integer Returns the integer portion of a number. | This functoid requires one input parameter. This functoid removes the decimal point of a number and any digits to the right of the decimal point.
Maximum Value functoid Maximum Value Returns the maximum value from a series of numeric values. | This functoid requires one or more input parameters.
Minimum Value functoid Minimum Value Returns the minimum value from a series of numeric values. | This functoid requires one or more input parameters.
Modulo functoid Modulo Returns the remainder after the number is divided by an integer. | This functoid requires two input parameters. This functoid returns the remainder of an integer division. This functoid is useful for determining less-than-load-type calculations, such as shipping quantities.
Round functoid Round Rounds a number to a specified number of decimal places or to a whole number if no decimal places are specified. | This functoid requires two input parameters. The first input linked to the functoid represents the value; the second input linked to the functoid represents the number of decimal places by which you want the number to be rounded. The functoid rounds up or down based on standard calculating rules.
Square Root functoid Square Root Returns the square root of a number. | This functoid requires one input parameter.
Addition functoid Addition Calculates the sum of a series of numbers. | This functoid requires one or more input parameters.
Subtraction functoid Subtraction Subtracts one number from another number. | This functoid requires one or more input parameters.
Multiplication functoid Multiplication Multiplies one number by another number. | This functoid requires one or more input parameters.
Division functoid Division Divides one number by another number. | This functoid requires two input parameters. You can use this functoid with real numbers and integers.


Logical Functoids

Functoid | Parameters
Greater Than functoid Greater Than Returns "true" if the first parameter is greater than the second parameter. | This functoid requires two input parameters.
Greater Than or Equal To functoid Greater Than or Equal To Returns "true" if the first parameter is greater than or equal to the second parameter. | This functoid requires two input parameters.
Less Than functoid Less Than Returns "true" if the first parameter is less than the second parameter. | This functoid requires two input parameters.
Less Than or Equal To functoid Less Than or Equal To Returns "true" if the first parameter is less than or equal to the second parameter. | This functoid requires two input parameters.
Equal functoid Equal Returns "true" if the first parameter is equal to the second parameter. | This functoid requires two input parameters.
Not Equal functoid Not Equal Returns "true" if the first parameter is not equal to the second parameter. | This functoid requires two input parameters.
Logical String functoid Logical String Returns "true" if the parameter is a string value. | This functoid requires one input parameter.
Logical Date functoid Logical Date Returns "true" if the parameter is a date value. | This functoid requires one input parameter.
Logical Numeric functoid Logical Numeric Returns "true" if the parameter is a numeric value. | This functoid requires one input parameter.
Logical OR functoid Logical OR Returns the logical OR of parameters. | This functoid requires one or more input parameters.
Logical AND functoid Logical AND Returns the logical AND of parameters. | This functoid requires one or more input parameters.
Logical Existence functoid Logical Existence Returns "true" if the input record or field exists in the source document. | This functoid can have only one input parameter.


Date and Time Functoids

Functoid | Parameters
Add Days functoid Add Days Adds a specified number of days to a date. | This functoid requires two input parameters. The first link must have date information as the input. The second link determines the number of days to add to the date.
Date functoid Date Returns the current date. | This functoid does not require any input parameters. The output format is YYYY-MM-DD.
Time functoid Time Returns the current time. | This functoid does not require any input parameters. The output format is HH:MM:SS.
Date and Time functoid Date and Time Returns the current date and time. | This functoid does not require any input parameters. The output format is YYYY-MM-DDTHH:MM:SS.


Conversion Functoids

Functoid | Parameters
ASCII from Character functoid ASCII from Character Returns an ASCII value when given a character. | This functoid requires one input parameter. This functoid converts an underlying ASCII value code. For example: A=97
Character from ASCII functoid Character from ASCII Returns a character when given an ASCII value. | This functoid requires one input parameter. This functoid converts a value to its underlying ASCII value code. For example: 98=B
Hexadecimal functoid Hexadecimal Returns a hexadecimal value when given a decimal number. | This functoid requires one input parameter. This functoid converts decimal to hexadecimal. For example: 10=A
Octal functoid Octal Returns an octal value when given a decimal number. | This functoid requires one input parameter. This functoid converts decimal to octal. For example: (Octal 0-7), 8=10, and 10=12


Scientific Functoids

Functoid | Parameters
Arc Tangent functoid Arc Tangent Returns the arc tangent of a number. | This functoid requires one input parameter. The input value must be in radians.
Cosine functoid Cosine Returns the cosine of a number. | This functoid requires one input parameter. The input value must be in radians.
Sine functoid Sine Returns the sine of a number. | This functoid requires one input parameter. The input value must be in radians.
Tangent functoid Tangent Returns the tangent of a number. | This functoid requires one input parameter. The input value must be in radians.
Natural Exponential Function functoid Natural Exponential Function Returns e raised to a specified power. | This functoid requires one input parameter.
Natural Logarithm functoid Natural Logarithm Returns the logarithm (base e) of a value. | This functoid requires one input parameter.
10^X Returns 10 raised to a specified power. | This functoid requires one input parameter.
Common Logarithm functoid Common Logarithm Returns the logarithm (base 10) of a value. | This functoid requires one input parameter.
X^Y Returns a value raised to a specified power. | This functoid requires two input parameters.
Base-Specified Logarithm functoid Base-Specified Logarithm Returns the logarithm (base-specified) of a value. | This functoid requires two input parameters.


Cumulative Functoids

Functoid Parameters
Cumulative Sum functoid Cumulative Sum

Sums all values for the connected field by iterating over its parent record.

 This functoid requires two input parameters. The second parameter specifies the hierarchy level (from the standpoint of the compiler link) from the source node. This parameter should be an integer greater than 0 and less than the node depth from the root node.

Note

  • This functoid provides backward compatibility with Microsoft BizTalk Server 2000, which required only one input parameter.

For more information and an example of cumulative functoids, see Using Cumulative Functoids.
Cumulative Average functoid Cumulative Average

Calculates the average of all values for the connected field by iterating over its parent record.

 This functoid requires two input parameters. The second parameter specifies the hierarchy level (from the standpoint of the compiler link) from the source node. This parameter should be an integer greater than 0 and less than the node depth from the root node.

Note

  • This functoid provides backward compatibility with BizTalk Server 2000, which required only one input parameter.

For more information and an example of cumulative functoids, see Using Cumulative Functoids.
Cumulative Minimum functoid Cumulative Minimum

Returns the minimum of input spanning over the parent record.

 This functoid requires two input parameters. The second parameter specifies the hierarchy level (from the standpoint of the compiler link) from the source node. This parameter should be an integer greater than 0 and less than the node depth from the root node.

Note

  • This functoid provides backward compatibility with BizTalk Server 2000, which required only one input parameter.

For more information and an example of cumulative functoids, see Using Cumulative Functoids.
Cumulative String functoid Cumulative Maximum

Returns the maximum of input spanning over the parent record.

 This functoid requires two input parameters. The second parameter specifies the hierarchy level (from the standpoint of the compiler link) from the source node. This parameter should be an integer greater than 0 and less than the node depth from the root node.

Note

  • This functoid provides backward compatibility with BizTalk Server 2000, which required only one input parameter.

For more information and an example of cumulative functoids, see Using Cumulative Functoids.
Cumulative String functoid Cumulative String

Returns the concatenated string of the string values for the connected field by iterating over its parent record.

 This functoid requires two input parameters. The second parameter specifies the hierarchy level (from the standpoint of the compiler link) from the source node. This parameter should be an integer greater than 0 and less than the node depth from the root node.

Note

  • This functoid provides backward compatibility with BizTalk Server 2000, which required only one input parameter.

For more information and an example of cumulative functoids, see Using Cumulative Functoids.


Database Functoids

Functoid | Parameters
Database Lookup functoid Database Lookup Searches a database for a specific value, retrieves the record that contains the value, and stores it as a Microsoft ActiveX® Data Objects (ADO) record set. | This functoid must have exactly four input parameters.
Value Extractor functoid Value Extractor Returns a value from a specific column in an ADO record set that has been retrieved by the Database Lookup functoid. | This functoid must have exactly two input parameters.
Error Return functoid Error Return Returns the error string, if any, returned by Open Database Connectivity (ODBC) when using the Database Lookup functoid. | This functoid must have exactly one input parameter.


Advanced Functoids

Functoid | Parameters
Scripting functoid Scripting Returns custom Microsoft® Visual Basic® Scripting Edition (VBScript) or custom Microsoft JScript®. | The number of input parameters for this functoid is configurable, based on a custom script.
Record Count functoid Record Count Returns a total count of the records found in the instance. | This functoid must have one input parameter.
Index functoid Index Returns the value of a record or a field at a specified index. | This functoid must have at least two input parameters. The maximum number of input parameters is limited by the number of levels in the specification hierarchy.
Iteration functoid Iteration Returns the iteration number (in a loop) of the source record. | This functoid must have one input parameter.
Value Mapping functoid Value Mapping Returns the value of the second parameter if the value of the first parameter is "true". | This functoid must have two input parameters.
Value Mapping (Flattening) functoid Value Mapping (Flattening) Returns the value of the second parameter if the value of the first parameter is "true", and flattens the source document hierarchy. | This functoid must have two input parameters.
Looping functoid Looping Creates multiple output records by iterating over each input record. | This functoid must have at least one input parameter. There is no maximum limit on the number of input parameters.


Edit Functoid Properties

  • To view the Functoid Properties dialog box, right-click a functoid in the mapping grid and click Properties.

    —Or—

    Double-click a functoid to view its properties.

Note

  • The General tab displays input-parameter information. The Script tab displays script information.

For information about how to use this dialog box, see the following topics:

  • Input Parameters

  • Functoid Scripts


Input Parameters

For information about how to access the Functoid Properties dialog box, see Edit Functoid Properties.

Input parameters for many functoids can be added, deleted, and moved up and down on the General tab of the Functoid Properties dialog box.

The following procedures are covered in this section:

  • Insert input parameters

  • Delete input parameters

  • Move input parameters

  • Rename input parameters

Note

  • Some functoids have limits on the number of parameters they can have. Information about how many parameters a particular functoid can have can be found beneath the Input parameters area on the General tab of the Functoid Properties dialog box for that functoid.


Insert input parameters

  1. Double-click a functoid in the mapping grid.

    The Functoid Properties dialog box appears.

  2. On the General tab, click the Insert New Parameter button Insert New Parameter button, type the information for the new parameter, and then press ENTER.

    Notes

    • If the Insert New Parameter button is unavailable, the functoid does not accept or require input parameters.

    • New parameter information is reflected on the Script tab.
  3. Repeat step 2 to add additional parameters, if necessary.

  4. Click OK.

Important

  • If you select the Script tab and manually modify an input parameter, any additional input parameters will not be reflected on the Script tab and will not be implemented at run time.

  • Double quotation marks are not supported within a constant value for an input parameter.

Related Topics

Delete input parameters

Move input parameters

Rename input parameters

Functoid Scripts


Delete input parameters

  1. Double-click a functoid in the mapping grid.

  2. On the General tab, in the Input parameters area, click the input parameter you want to delete.

  3. Click the Delete Selected Parameter button [image] and click OK.

Related Topics

Insert input parameters

Move input parameters

Rename input parameters


Move input parameters

  1. Double-click a functoid in the mapping grid.

  2. On the General tab, in the Input parameters area, click the input parameter you want to move.

  3. Click the Move Up Selected Parameter button [image] to move the parameter up, or click the Move Down Selected Parameter button Move Down Selected Parameter button to move the parameter down, and click OK.

Related Topics

Delete input parameters

Insert input parameters

Rename input parameters


Rename input parameters

  1. Double-click a functoid in the mapping grid.

  2. On the General tab, in the Input parameters area, right-click the input parameter you want to rename and click Change Value.

  3. Type a new parameter name and click OK.

Related Topics

Delete input parameters

Insert input parameters

Move input parameters


Functoid Scripts

For information about how to access the Functoid Properties dialog box, see Edit Functoid Properties.

You can view or edit scripts on the Script tab of the Functoid Properties dialog box.

Note

  • You can view the script for any functoid, but you can edit only the script of a Scripting functoid.

Related Topic

Input Parameters


Manage Links

The following topics are covered in this section:

  • Create links between fields

  • Create links between fields and functoids

  • Create links between records and fields

  • Create links between records and functoids

  • Create links between functoids

  • Allow record content links

  • Redirect links

  • Delete links


Create links between fields

  • Drag a field from the Source Specification tree to a field in the Destination Specification tree.

Important

  • The data type of a field in the Source Specification tree should match the data type of a field to which it is linked in the Destination Specification tree.

  • BizTalk Mapper checks for the existence of an attribute or element for a direct link from the source and destination before generating XSLT. Therefore, if the source field does not appear in the instance document (because it is optional), a blank destination field is created. This is unacceptable behavior because the destination field should be created only when the source field exists. To resolve this issue, check to see if the linked field is optional in the source schema. If it is, BizTalk Server generates an <xsl:if> clause to check for the existence of the source field before it creates the destination field. This ensures that the destination field is not created if the source field is absent in the source instance. When the source instance contains the field, the destination field is created as expected.

Notes

  • You cannot link to a node in a destination specification that has a destination constant value associated with it.

  • You cannot link to a required field in a destination specification that has a default value associated with it. For more information about making a field required, see Set reference properties. For more information about setting the default value of a field, see Set declaration properties.

  • You might need to expand the specification trees to view the fields that you want to map. For more information, see Expand tree items.

Related Topics

Add constant values

Manage Views

Set declaration properties

Set reference properties

Summary of Data Types and Data Type Values


Create links between fields and functoids

  • Drag a field from the Source Specification tree or the Destination Specification tree to a functoid in the mapping grid.

    -Or-

    Drag the functoid from the mapping grid to a field in the Source Specification tree or Destination Specification tree.

Important

  • A field with a certain data type property in the Destination Specification tree of a map should not be linked to a functoid that produces output of a different data type.

Notes

  • You must first add a functoid to the mapping grid before you can add a link from a field to the functoid. For more information about adding a functoid to the mapping grid, see Work with Functoids.

  • You cannot link to a node (in a destination specification) that has a destination constant value associated with it.

  • You cannot link to a required field (in a destination specification) that has a default value associated with it. For more information about making a field required, see Set reference properties. For more information about setting the default value of a field, see Set declaration properties.

Related Topics

Add constant values

Manage Views

Set declaration properties

Set reference properties

Work with Functoids


Create links between records and fields

  1. On the Tools menu, click Options.

  2. In the BizTalk Mapper Options dialog box, select the Allow record content links check box and click OK.

  3. Drag a record from the Source Specification tree to a field in the Destination Specification tree.

    —Or—

    Drag a record from the Destination Specification tree to a field in the Source Specification tree.

Notes

  • You cannot link to a node in a destination specification that has a destination constant value associated with it.

  • You cannot link to a required field in a destination specification that has a default value associated with it. For more information about making a field required, see Set reference properties. For more information about setting the default value of a field, see Set declaration properties.

  • You might need to expand the specification trees to see the records and fields that you want to map. For more information, see Expand tree items.

Related Topics

Add constant values

Manage Views

Set declaration properties

Set reference properties


Create links between records and functoids

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Select the Allow record content links check box and click OK.

  3. Drag a record from the Source Specification tree or the Destination Specification tree to a functoid in the mapping grid.

    -Or-

    Drag the functoid from the mapping grid to a record in the Source Specification tree or Destination Specification tree.

Notes

  • You must first add a functoid to the mapping grid before you can add a link from a record to the functoid.

  • You cannot link to a node in a destination specification that has a destination constant value associated with it. For more information about destination constant values, see BizTalk Mapper User Interface.

Related Topics

Add constant values

Manage Views


Create links between functoids

  • Drag one functoid to another functoid in the mapping grid.

Note

  • Links are processed left to right in the mapping grid. You cannot make a link from one functoid to another functoid directly above or below it.

Related Topics

Create links between fields and functoids

Create links between records and functoids


Allow record content links

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Select the Allow record content links check box and click OK.

  3. Drag a record from the Source Specification tree to a record in the Destination Specification tree.


Redirect links

  1. In the mapping grid, click a link to highlight it.

    The endpoints of the links are highlighted with small blue boxes.

  2. Drag either endpoint to the functoid or node to which you want to connect.

    As you drag an endpoint, the pointer becomes a crosshair. If you point to an object to which a link cannot be made, the pointer becomes a circle with a line through it.

Important

  • If you have two or more source links connected to a functoid and you redirect one or more of those source links to different nodes in the Source Specification tree, the order of the functoid's input parameters might not be preserved. Double-click the functoid to view its input parameters and ensure that they are in the correct order.


Delete links

  1. Right-click the link you want to delete and click Delete.

  2. Click Yes in the confirmation dialog box.


View Grid Links and Functoids

The following topics are covered in this section:

  • View links and functoids in the mapping grid

  • View links and functoids by using the grid preview


View links and functoids in the mapping grid

  1. Move the cursor into the mapping grid, near the edge, in the direction that you want to scroll.

    The cursor changes from a pointer or pipe (|) to a large arrow.

  2. Click and hold the left mouse button to scroll in the direction that the arrow points.

Note

  • You can also scroll by clicking in the mapping grid background and then using the arrow keys to scroll in all four directions.

Related Topics

BizTalk Mapper User Interface

View links and functoids by using the grid preview


View links and functoids by using the grid preview

  1. On the View menu, click Grid Preview.

    The Grid Preview window opens to display a representation of where the functoids are located on the mapping grid.

  2. Drag the green locator bar to a new location on the Grid Preview dialog box.

    As you move the green locator bar, links and functoids in the mapping grid also move.

Note

  • The grid preview is useful for navigating the mapping grid when you have many functoids spread out over the mapping grid.

Related Topics

BizTalk Mapper User Interface

View links and functoids in the mapping grid


Edit Link Properties

  • To view the Link Properties dialog box, right-click a link in the mapping grid and click Properties.

    The General tab appears by default.

For information about how to use this dialog box, see the following topics:

  • View Link Properties: General Tab

  • View Link Properties: Compiler Tab

Note

  • You also can double-click a link to view its properties.

Related Topics

Compiling Maps

Manage Links


View Link Properties: General Tab

For information about how to access the Link Properties dialog box, see Edit Link Properties.

The General tab displays information about the source and destination of a link. The Source area displays the record path, field path, or functoid name for the link source, depending on whether the link source is a record, a field, or a functoid. The Destination area displays the record path, field path, or functoid name for the link destination, depending on whether the link destination is a record, a field, or a functoid.

Related Topic

View Link Properties: Compiler Tab


View Link Properties: Compiler Tab

For information about how to access the Link Properties dialog box, see Edit Link Properties.

The Compiler tab displays an area for setting compiler properties for source-specification links and an area for setting compiler properties for destination-specification links. For information about changing these settings, see the following topics:

  • Select compiler properties for source-specification links

  • Select compiler properties for destination-specification links

Related Topic

View Link Properties: General Tab


Select compiler properties for source-specification links

  1. Right-click a link in the mapping grid that is connected to a node in the Source Specification tree and click Properties.

    The Link Properties dialog box appears.

  2. Click the Compiler tab and click one of the following options in the Source specification links area:
    • Copy text value (default). Copies the value of the node in the incoming document instance. For example, <Node>Hello<Name>Chris</Name>Cannon</Node> would result in "Hello."

    • Copy text and sub-content value. Copies the concatenated value of the node and all values of descendants of it in the incoming document instance. For example, <Node>Hello<Name>Chris</Name>Cannon</Node> would result in "Hello Chris Cannon"

    • Copy name. Copies the name of the node in the incoming document instance.
  3. Click OK.

Important

  • If an element contains mixed content, for example data interspersed with child elements, and you select Copy text value (default), the only content that will be copied is the content that exists up to the first child element. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item being copied.

  • If an element contains mixed content, for example data interspersed with child elements, and you select Copy text and sub-content value, all the content, including the child elements, will be copied. For example:
    <A>Item<B>1</B><B>12</B><B>13</B><B>14</B>Number</A>

    Results in Item1121314Number being copied.

Related Topic

Select compiler properties for destination-specification links


Select compiler properties for destination-specification links

  1. Right-click a link in the mapping grid that is connected to a node in the destination specification and click Properties.

  2. Click the Compiler tab and select one of the following options in the Destination specification links area:
    • Flatten links (default). This mode means that all the source hierarchies are flattened to the parent of the destination node.

    • Match links top-down. This mode matches level to level from the top down.

    • Match links bottom-up. This mode matches level to level from the bottom up.
  3. Click OK.

Notes

  • If you use a flatten compiler directive, a top-down compiler directive, and a bottom-up compiler directive for links from fields in the Source Specification tree to fields in the Destination Specification tree that share the same parent record, BizTalk Mapper treats all the links as if they were set to the flatten compiler directive.

  • If you use one or more flatten compiler directives and a top-down compiler directive for links from fields in the Source Specification tree to fields in the Destination Specification tree that share the same parent record, BizTalk Mapper treats all the links as if they were set to the top-down compiler directive.

  • If you use one or more flatten compiler directives and a bottom-up compiler directive for links from fields in the Source Specification tree to fields in the Destination Specification tree that share the same parent record, BizTalk Mapper treats all the links as if they were set to the bottom-up compiler directive.

  • If you use one or more top-down compiler directives and one or more bottom-up compiler directives for links from fields in the Source Specification tree to fields in the Destination Specification tree that share the same parent record, BizTalk Mapper treats all the links as if they were set to the flatten compiler directive.

Related Topics

Matching Node-Hierarchy Levels

Select compiler properties for source-specification links


Create and Manage Compiled Maps

The following procedures are covered in this section:

  • Compile maps

  • Resolve warnings and errors after compiling a map

  • Add constant values


Compile maps

  • On the Tools menu, click Compile Map.

Caution

  • BizTalk Mapper generates a warning on the Warnings tab when the compiler encounters a situation that yields incorrect results. A map must generate no warnings before it can be considered ready for a production environment.

Note

  • If a warning appears, the problem might exist over several grid pages. For example, if you have grid page 1 with a record (named Item) in the Source Specification tree linked to a record (named Number) in the Destination Specification tree, and on grid page 2 you have a record (named Product) in the Source Specification tree linked to the same Number record in the Destination Specification tree, a warning message will be generated stating that you have multiple inputs to the same record. However if you view grid page 1, you will see only one input into the Number record.

Related Topic

Resolve warnings and errors after compiling a map


Resolve warnings and errors after compiling a map

If a warning appears, the problem might exist over several grid pages. For example, if you have grid page 1 with a record (named Item) in the Source Specification tree linked to a record (named Number) in the Destination Specification tree, and on grid page 2 you have a record (named Product) in the Source Specification tree linked to the same Number record in the Destination Specification tree, a warning message will be generated stating that you have multiple inputs to the same record. However if you view grid page 1, you will see only one input into the Number record.

  1. Double-click a warning on the Warnings tab.

    The link, functoid, or node that relates to the warning or error is highlighted in the mapping grid.

  2. Modify the link, functoid, or node as needed.

  3. Repeat steps 1 and 2 for each warning.

  4. On the Tools menu, click Compile Map.

Related Topic

Compile maps


Add constant values

  1. Select a record or field in the Destination Specification tree and click the Values tab.

  2. In the Destination constant value box, type a value that you want associated with the record or field.

Notes

  • You cannot create a link to a record or field that has a constant value associated with it.

  • You can only associate a constant value with a record with its Content property set to Text Only or Mixed. For more information about the Content property, see Set declaration properties.

Related Topic

Set declaration properties


Perform Map Testing

The following procedures are covered in this section:

  • Test record and field properties that have links

  • Test maps


Test record and field properties that have links

Important

  • Always compile a map prior to testing it so you can resolve warnings and errors. For more information, see Compile maps.
  1. Click a field in the Source Specification tree that is connected to a link.

  2. Click the Values tab.

  3. Type a value in the Source test value box.

  4. On the Tools menu, point to Test Map, and then click the option you want.

    Important

    • Before the test begins, you are prompted to save your file. Save your file prior to testing it as a precautionary measure to preserve your data in case any problems are accidentally introduced into the map.
  5. Click Yes to save the map.

  6. Verify the results on the Output tab.

Note

  • If the Maximum Occurrences property for a record is an asterisk (*), this indicates that it is a looping record. The incoming document instance that BizTalk Mapper generates to test the map contains two occurrences of the record.

Related Topics

Compile maps

Test maps


Test maps

Important

  • Always compile a map prior to testing it so you can resolve warnings and errors. For more information, see Compile maps.

  • If you want to validate content before you test a map:
    1. On the Tools menu, click Options.

      The BizTalk Mapper Options dialog box appears.

    2. On the General tab, select Validate content before map test and click OK.

    Note

    • If one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XML-Data Reduced (XDR) file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.
  • If you want to validate content after you test a map:
    1. On the Tools menu, click Options.

      The BizTalk Mapper Options dialog box appears.

    2. On the General tab, select Validate content after map test and click OK.

    Note

    • If one of the specifications you are using in your map is a non-BizTalk Server-based specification, such as an XML-Data Reduced (XDR) file, and you use the content validation feature, validation might fail. If warnings, especially those related to namespaces or element groups, appeared when you opened the XDR file, you should not use the content validation feature.
  1. On the Tools menu, point to Test Map, and then click the option you want.

    Important

    • Before the test begins, you are prompted to save your file. Save your file prior to testing it as a precautionary measure to preserve your data in case any problems are accidentally introduced into the map.
  2. Click Yes to save the map.

  3. If warnings are generated during the compile process, a message box appears. Click Yes to continue.

  4. If you selected Generated XML to Native and the output schema is an EDI-based structure, you will need to specify delimiters in the Document Delimiters dialog box. For more information about specifying delimiters, see BizTalk Mapper Options: Document Delimiters.

    —Or—

    If you selected either Instance XML to XML or Instance XML to Native, then the Load Instance XML File dialog box appears. Browse to locate an instance file and click Open.

    —Or—

    If you selected Native Instance to XML or Native Instance to Native, then the Load Native Instance File dialog box appears. Browse to locate an instance file and click Open.

    Notes

    • The Generated XML to Native and Instance XML to Native options are not available if the output schema is XML.

    • The Native Instance to Native is not available if the input or output schema is XML.

    • If an EDI interchange has multiple documents in it, only the first document instance is used in the test map.

    • If the Prompt for delimiters during instance test box is selected, and the instance you are testing is an EDI file with envelope information, the Document Delimiters dialog box will not appear because BizTalk Mapper will automatically detect the delimiter needed. BizTalk Mapper will display the Prompt for delimiters during instance test box, even if you have specified to have it displayed during instance testing, only if it cannot determine the delimiters to use.
  5. Verify the results on the Output tab.

Important

  • In rare cases, BizTalk Mapper might not be able to map data in a single transformation. However, Biztalk Server provides the capability to map a document twice, synchronously, through two iterations using SubmitSync and LoopBack as the primary transports in the Port configuration. Thus, you can break your mapping into various stages by reusing and combining different channels. For more information, see the sample folder Mapping Twice located in \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples.

  • Character ranges are ignored. Therefore, if you have character restrictions applied to your map and they are not met, you will still see that your test map was successful. However, when BizTalk Server attempts to parse your transaction, it will fail.

  • Although you might successfully create a native instance, if you later complete instance validation, it will fail if syntax rules are not met.

Related Topics

Compile maps

Testing Maps


Manage Views

The following procedures are covered in this section:

  • Expand tree items

  • Collapse tree items

  • 6View record and field properties

  • Adjust the pane size for the Source Specification tree

  • Adjust the pane size for the Destination Specification tree

  • Adjust the size of the lower pane


Expand tree items

  • Click the root node or a record in the specification tree that you want to expand and, on the View menu, click Expand Tree Items.

    —Or—

    Right-click the root node or a record in a tree and click Expand Tree Items.

Related Topic

Collapse tree items


Collapse tree items

  • Click the root node or a record in the specification tree that you want to collapse and, on the View menu, click Collapse Tree Items.

Note

  • You also can right-click the root node or a record in a tree and click Collapse Tree Items.

Related Topic

Expand tree items


View record and field properties

  • Click a record or field in either the Source Specification tree or the Destination Specification tree and, on the View menu, click Properties.

    —Or—

    Click a record or field in either tree and click the Properties tab.

Note

  • You might need to drag the scroll bar on the Properties tab to view a specific property and its associated value.


Adjust the pane size for the Source Specification tree

  1. Place the cursor on the right border of the Source Specification tree pane until the cursor becomes a two-headed arrow.

  2. Drag the border to the right to increase the pane size or to the left to decrease the pane size.

Note

  • Double-click the border to restore it to its default position.

Related Topics

Adjust the pane size for the Destination Specification tree

Adjust the size of the lower pane


Adjust the pane size for the Destination Specification tree

  1. Place the cursor on the left border of the Destination Specification tree pane until the cursor becomes a two-headed arrow.

  2. Drag the border to the left to increase the pane size or to the right to decrease the pane size.

Note

  • Double-click the border to restore it to its default position.

Related Topics

Adjust the pane size for the Source Specification tree

Adjust the size of the lower pane


Adjust the size of the lower pane

  1. Place the cursor on the top border of the lower pane until the cursor becomes a two-headed arrow.

  2. Drag the pane upward to increase the pane size or downward to decrease the pane size.

Note

  • Double-click the border to restore it to its default position.

Related Topics

Adjust the pane size for the Destination Specification tree

Adjust the pane size for the Source Specification tree


Customize the User Interface

The following procedures are covered in this section:

  • Change mapping grid colors

  • Change the color of links

  • Change the color of selected objects

  • Change the color of compiler warnings

  • Restore default colors

  • Change text size


Change mapping grid colors

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Colors tab.

  3. Click the box next to Grid foreground, which represents the dashed lines in the mapping grid, and, in the color palette, select a new color.

    –Or–

    Click the box next to Grid background, which represents the background color of the mapping grid, and, in the color palette, select a new color.

  4. Click OK.

Related Topics

Change the color of compiler warnings

Change the color of links

Change the color of selected objects

Restore default colors


Change the color of links

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Colors tab.

  3. Click the box next to one of the following:
    • Fixed links. Fixed links are simple value-copy links in the mapping grid.

    • Elastic links. Elastic links are simple value-copy links that are dragged from the Source Specification tree to the Destination Specification tree. Once the link is made, the color of the link changes to the predefined fixed links color.

    • Partial links. Partial links are links that exist for a field or record whose parent record is collapsed.

    • Compiler links. Compiler links are the compiler directive links. They are links that are automatically created when a link is set from a field in the Source Specification tree to a field in the Destination Specification tree.
  4. In the color palette, select a new color.

  5. Repeat step 3 to change other colors, if necessary.

  6. Click OK.

Related Topics

Change mapping grid colors

Change the color of compiler warnings

Change the color of selected objects

Restore default colors


Change the color of selected objects

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Colors tab.

  3. Click the box next to Selected objects and, in the color palette, select a new color.

  4. Click OK.

Related Topics

Change mapping grid colors

Change the color of compiler warnings

Change the color of links

Restore default colors


Change the color of compiler warnings

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Colors tab.

  3. Click the box next to Compiler warnings and, in the color palette, select a new color.

  4. Click OK.

Related Topics

Change mapping grid colors

Change the color of links

Change the color of selected objects

Restore default colors


Restore default colors

  1. On the Tools menu, click Options.

    The BizTalk Mapper Options dialog box appears.

  2. Click the Colors tab.

  3. Click Restore Default Colors and click OK.

Related Topics

Change mapping grid colors

Change the color of compiler warnings

Change the color of links

Change the color of selected objects


Change text size

  • On the View menu, point to Text Size and click the size that you want.


BizTalk Mapper Shortcut Keys

You can use shortcut keys to accomplish tasks in BizTalk Mapper. The following table is a quick reference to these shortcut keys.

Note

  • Functionality that is not included in this list can be obtained by using the numeric keypad to move the mouse pointer with MouseKeys. For more information about MouseKeys in Windows 2000 Server and Advanced Server Help, see "Using the keyboard to move the mouse pointer." For more information about MouseKeys in Windows 2000 Professional Help, see "Move the mouse pointer by using MouseKeys."
Press | To
CTRL+N | Open a new specification.
CTRL+O | Open an existing map.
CTRL+S | Save a map.
CTRL+F5 | Test a map.
F4 | Highlight the next warning.
F5 | Compile a map.
CTRL+A | Add a grid page.
On a grid page name, F2 | Rename a grid page.
CTRL+D | Delete a grid page.
DEL | Delete an object in the mapping grid.
F6 | Move the focus clockwise from pane to pane.
SHIFT+F6 | Move the focus counterclockwise from pane to pane. Pressing SHIFT+F6 after opening the functoid palette moves the focus to the String tab, allowing you to use the left and right arrow keys to view the other tabs.
SHIFT+F10 | Open the context menu for highlighted items.
TAB | Move the focus clockwise in the lower pane from the tab to the panes or fields below. In a dialog box, pressing TAB moves the focus through the buttons and fields of the dialog box. In addition, this enables you to access the buttons in the upper right corner of the Select Source Specification Type dialog box.
SHIFT+TAB | Move the focus counterclockwise in the lower pane from the tab to the panes or fields below.
SPACEBAR | Select or clear a check box. The spacebar also acts like a mouse click when the focus is on a button.
F1 | View online Help.
ALT+F4 | Exit from the program.
Arrow keys | Move the focus in the Grid Preview window.
LEFT ARROW | Activate the tab to the left.
RIGHT ARROW | Activate the tab to the right.
Any arrow key | Highlight a folder or a file in the main pane of a dialog box, while the focus is on that pane. This functionality occurs in the Store to WebDAV dialog box and the Retrieve from WebDAV dialog box. For more information, see Retrieve maps from WebDAV.

Using MouseKeys with BizTalk Mapper

Some operations in BizTalk Mapper have no keyboard shortcuts. To perform the following operations, you must use MouseKeys:

  • Move

  • Select functoids

  • Drag functoids

  • Linking


Troubleshooting BizTalk Editor and BizTalk Mapper

This section provides a centralized location for information related to troubleshooting Microsoft® BizTalk™ Editor and BizTalk Mapper. If you are having difficulty with BizTalk Editor or BizTalk Mapper, try to find a solution here.

The following topics are covered in this section:

  • Password required when trying to connect to a remote WebDAV server

  • Failure to connect to WebDAV or to store files to WebDAV

  • ???.xml appears in the WebDAV dialog box

  • BizTalkServerRepositoryMaps folder appears in Retrieve from WebDAV dialog box

  • Retrieve from WebDAV dialog box or Store to WebDAV dialog box is empty

  • Failure to connect to http://localhost

  • Flat file not completely parsed when submitted to BizTalk Server

  • White space not preserved in flat files submitted to BizTalk Server

  • Test map fails

  • DTD import fails

  • Instance validation fails when using the Date or Time field

  • Re-register msdaipp.dll to retrieve or store maps in WebDAV

  • The parser cannot find the required leading delimiter

  • Storing a file to WebDAV fails

  • Importing an XML-Data Reduced file fails

  • Instance validation fails when using a comma to express a decimal number

  • Large data segments in an IDOC document are not posted to an SAP system

  • Unicode limitations in WebDAV

  • X12 templates contain an implied decimal

  • Using the keyboard to convert Korean characters to Chinese characters causes BizTalk Editor to fail

  • Cannot open BizTalk Editor or BizTalk Mapper


Password required when trying to connect to a remote WebDAV server

Cause: User might not have access to the BizTalkServerRepository folder.

Solution: Provide user with access to the BizTalkServerRepository folder. To do this:

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  2. In the console tree, expand the name of the computer.

  3. Expand Default Web Site.

  4. Right-click BizTalkServerRepository and click Properties.

    The BizTalkServerRepository Properties dialog box appears.

  5. Click the Directory Security tab.

  6. In the Anonymous access and authentication control area, click Edit.

  7. Select the Anonymous Access check box and click OK twice.


Failure to connect to WebDAV or to store files to WebDAV

Cause One: If you attempt to retrieve a map or a specification from WebDAV, or store a map or specification to WebDAV, you might see one of the following messages:

The file cannot be stored in the WebDAV repository. The server may not be available at this time.

No key matching the described characteristics could be found within the current range.

This occurs when the anonymous setting for the user account on the Web server does not have write privileges on the Microsoft® Windows® 2000 directory that hosts the repository.

Solution: Give user access to the repository. To do this:

  1. On the Start menu, point to Programs, point to Accessories, and then click Windows Explorer.

  2. Navigate to the location in which you installed Microsoft BizTalk Server 2002.

  3. Expand the Microsoft BizTalk Server directory, right-click BizTalkServerRepository, and then click Properties.

    The BizTalkServerRepository Properties dialog box appears.

  4. Click the Security tab.

  5. Click Add and type the domain name and the user name for the person you want to have permission to the repository in the following format: domain name\user name.

  6. Click OK twice.

Cause Two: If you attempt to retrieve a map or a specification from WebDAV, or store a map or specification to WebDAV, you might see the following message:

No BizTalk Server repository was found on http://localhost/BizTalkServerRepository/DocSpecs. Enter another server name to retry the WebDAV connection.

This occurs when Microsoft FrontPage® Server Extensions are enabled on the Web server.

Solution: Disable FrontPage Server Extensions. If the World Wide Web Publishing service is running, stop and restart this service.

Note

  • This problem can occur even if the World Wide Web Publishing Service is not running on the computer hosting the WebDAV repository.

To disable FrontPage Server Extensions

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  2. In the details pane, double-click <name of the computer>, right-click Default Web Site, and then click Properties.

    The Default Web Site Properties dialog box appears.

  3. On the Server Extensions tab, clear the Enable authoring check box and click OK.

To stop and restart the World Wide Web Publishing Service

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Component Services.

  2. In the console tree, click Services (local).

  3. In the details pane, right-click World Wide Web Publishing Service and click Stop.

  4. Right-click World Wide Web Publishing Service and click Start.


???.xml appears in the WebDAV dialog box

International Issue

Cause: The set of characters that is displayed for your computer is dependent on the locale setting specified in BizTalk Server.

Solution: Specify the same character set for your computer as for the locale setting specified in BizTalk Server. To do this:

  1. On the Start menu, point to Settings, and then click Control Panel.

  2. Double-click Regional Options.

  3. On the General tab, in the Language settings for the system area, select the check box for the desired language and click Set Default.

    The Select System Locale dialog box appears.

  4. Click the desired locale in the list and click OK twice.

    The Change Regional Options dialog box appears.

  5. Click Yes to accept the changes and restart your computer.

Note

  • After restarting your computer, the selected language in the Regional Options dialog box displays the following information: <Language> (default).

Related Topics

Store maps

Store specifications


BizTalkServerRepositoryMaps folder appears in Retrieve from WebDAV dialog box

Cause: There is a trailing backslash in the Local Path box of the BizTalkServerRepository Properties dialog box.

Solution: Remove the trailing backslash in the Local Path edit box of the BizTalkServerRepository Properties dialog box. To do this:

  1. On the Start menu, point to Programs, point to Administrative Tools, click Internet Information Services, and then expand Default Web Site.

  2. Right-click BizTalkServerRepository and click Properties.

    The BizTalkServerRepository Properties dialog box appears.

  3. In the Local Path edit box, remove the trailing backslash and click OK.

Completing this procedure removes the BizTalkServerRepositoryMaps folder from the Retrieve from WebDAV dialog box. This folder is unusable, so it is recommended that you remove it.


Retrieve from WebDAV dialog box or Store to WebDAV dialog box is empty

Cause: Directory browsing is disabled in the BizTalkServerRepository Properties dialog box.

Solution: Enable directory browsing in the BizTalkServerRepository Properties dialog box. To do this:

  1. On the Start menu, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  2. Expand the computer that you are troubleshooting.

  3. Expand Default Web Site.

  4. Right-click BizTalkServerRepository and click Properties.

    The BizTalkServerRepository Properties dialog box appears.

  5. On the Virtual Directory tab, select Directory browsing.

  6. Ensure that Read and Write are also selected and click OK.


Failure to connect to http://localhost

Cause: The Use a proxy server check box is selected, but the Bypass proxy server for local addresses check box is not selected.

Solution: Keep the Use a proxy server setting on, and turn on the Bypass proxy server for local addresses setting. To do this:

  1. On the Start menu, point to Programs and click Internet Explorer.

  2. On the Tools menu, click Internet Options.

    The Internet Options dialog box appears.

  3. Click the Connections tab and click LAN Settings.

    The Local Area Network (LAN) Setting dialog box appears.

  4. In the Proxy Server area, select the Bypass proxy server for local addresses check box.

  5. Click OK twice.

Note

  • This failure will not occur if you connect to http://<name of the computer>.


Flat file not completely parsed when submitted to BizTalk Server

Cause: A delimited flat file might have a parsing error when submitted to BizTalk Server if the file has the name of the root node as a sub-string of the name of another node in the file.

Solution: Rename the root node so that its name is not a sub-string of the name of any other node in the specification.


White space not preserved in flat files submitted to BizTalk Server

Cause: When a flat file is submitted to BizTalk Server, white space in fields might be trimmed. This is because by default the underlying MSXML parser does not preserve white space in a field with its Type property (on the Declaration tab) set to Element.

Solution: If it is important to preserve white space in a field contained in a flat file, in BizTalk Editor be sure to set the Type property on the Declaration tab of the field in the source specification to Attribute.

Related Topic

Set declaration properties


Test map fails

Cause: When you test a map, BizTalk Mapper compiles the map before testing it. If a warning occurs during the compile, the test map might not succeed. The following error message appears:

The Extensible Stylesheet Language (XSL) transformation using the test instance document of the source specification failed.

Solution: Resolve all compiler warnings and then recompile the map. To resolve a compiler warning, complete the following:

  1. Double-click the word Warning on the Output tab.

    This highlights the link or functoid associated with the warning message.

  2. Resolve the warning as needed.

To recompile the map:

  • On the Tools menu, click Compile Map.

Related Topic

Testing Maps


DTD import fails

Cause: If you try to import a document type definition (DTD) that contains an external reference to another file, you might see the following message:

Invalid character found in DTD.

Solution: Remove any external references in a DTD before attempting to import it.


Instance validation fails when using the Date or Time field

Cause: While BizTalk Server is processing an incoming document instance, if there is a link from a functoid or field in the Source Specification tree to a node in the Destination Specification tree with its Data Type property set to Date, Date Time, Date Time.tz, Time, or Time.tz, instance validation fails if the data coming into the node in the Destination Specification tree is in any format other than ISO 8601.

Solution: When you link to a field in a Destination Specification tree with its Data Type property set to Date, Date Time, Date Time.tz, Time, or Time.tz, make sure the data that links to that field (whether from a functoid or from a node in an incoming document instance) is in ISO 8601 format. The following table shows the correct ISO 8601 format for each of the possible Data Type property values.

Data Type property | ISO 8601 format
Date | YYYY-MM-DD (1988-04-07)
Date Time | YYYY-MM-DDTHH:MM:SS (1988-04-07T18:39:09)
Date Time.tz | YYYY-MM-DDTHH:MM:SS-TZH:TZM (1988-04-07T18:39:09-08:00)
Time | HH:MM:SS (08:15:27)
Time.tz | HH:MM:SS-TZH:TZM (08:15:27-05:00)


Re-register msdaipp.dll to retrieve or store files in WebDAV

Cause: If you attempt to retrieve a map or a specification from WebDAV, or store a map or specification to WebDAV, you might see the following message:

No BizTalk Server Repository was found on http://<server name>/BizTalkServerRepository/DocSpecs

Solution: To resolve this issue, complete the following steps:

  1. In Windows Explorer, browse to \Program Files\Common Files\System\Ole DB\ and double-click msdaipp.dll.

    The Caution dialog box appears.

  2. Click Open With.

    The Open With dialog box appears.

  3. Click Other.

    The Open With dialog box appears.

  4. Browse to \WINNT\system32\ and double-click regsvr32.exe.

    The Open With dialog box appears.

  5. Make sure Microsoft© Register Server is selected and click OK.

    A message box appears.

  6. Click OK.


The parser cannot find the required leading delimiter

Cause: If the document instance you are using has fields within a record that are both optional and empty, you must add a field delimiter before the record delimiter. For example, the following document instance contains a tilde (~) for the record delimiter. However, it also shows a plus sign (+) as the field delimiter for the first record. This requires that you set the Record Delimiter as ~ and the Field Delimiter as + in the Document Delimiters dialog box.

Document instance containing a tilde for the record delimiter

When you validate the previous document instance against the following specification illustration, the following error appears:

While parsing record "Record1", the parser could not find the required leading delimiter: "+" (0x002b).

Validating a document instance against a specification

Solution: To resolve this issue, add a "+" between the "TTT" and the "~" in the document instance.


Storing a file to WebDAV fails

Cause: If storing a file from BizTalk Editor or BizTalk Mapper to the WebDAV repository fails (for example, permission is denied or the file is read-only) then the appropriate error message appears. However, if you close the file and retrieve it again from WebDAV, you will be viewing the locally cached file rather than the one from the WebDAV repository. The file will appear as if it was stored from the WebDAV repository even though the Permission Denied dialog box appears.

Solution: Clear the Internet Explorer cache. To clear the cache, do the following:

  1. On the Start menu, point to Programs and click Internet Explorer.

  2. On the Tools menu, click Internet Options.

    The Internet Options dialog box appears.

  3. Click Delete Files.


Importing an XML-Data Reduced file fails

Cause: XML-Data Reduced (XDR) import will fail if the default value for an attribute of type IDREFS is specified in the attribute declaration, as shown in the following code:

<AttributeType name="Field1" d:type="idrefs" default="a1 a2"> </AttributeType>
<attribute type="Field1" required="no"></attribute>

Solution: Move the default value to the attribute reference in the XDR schema before importing it into BizTalk Editor, as shown in the following code:

<AttributeType name="Field1" d:type="idrefs"> </AttributeType>
<attribute type="Field1" required="no" default="a1 a2"></attribute>


Instance validation fails when using a comma to express a decimal number

Cause: If a comma (,) is used instead of a period (.) when expressing a decimal number in a document instance, instance validation might fail. This happens because the parser converts the document instance into an Extensible Markup Language (XML) document and then uses the XML Document Object Model (DOM) to validate the XML document against the specification. The XML DOM does not allow a comma to be used as a decimal point. For more information, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search for XML Data Types Reference.

Solution: Use a period when expressing decimal numbers in a document instance.


Large data segments in an IDOC document are not posted to an SAP system

Cause: When large data segments are used in an IDOC document that is routed to an SAP system for processing, some of the data might not be processed. This may be caused by a timeout value configured on the SAP system.

Solution: Change the timeout value on the SAP system.


Unicode limitations in WebDAV

International Issue

Cause: WebDAV does not support Unicode characters in file names. However, the files themselves can be saved only in Unicode encodings in the repository.

Solution: Make sure that the system locale set on your computer supports your language. For example, if you install the English version of BizTalk Server 2002 on a computer running the English version of Windows and want to name your files with characters not supported in the Latin I code page (Windows 1252 including English), you must set the system locale to a locale supporting your language.

For the Korean and Chinese languages, you also need to make sure that your Internet browser is not set to send URLs as UTF-8. To make sure this option is not set, do the following:

  1. On the Start menu, point to Programs and click Internet Explorer.

  2. On the Tools menu, click Options.

    The Internet Options dialog box appears.

  3. Select the Advanced tab and clear the Always send URLs as UTF-8 check box.


X12 templates contain an implied decimal

Cause: When the X12 templates included with BizTalk Server 2002are used in BizTalk Editor or BizTalk Mapper, you might encounter an error message similar to the following:

The length of the "ITD05" field ("") is not valid; it must be between 48 and -1. This document will be rejected.

The X12 templates use the implied decimal data type Nx, which affects validation and mapping. If the input data contains a decimal point, output will not match the Nx custom data type (which means no decimal point) and will create invalid document instances in the intermediate XML file.

Solution: Manually change the implied decimal data type in the X12 templates to any other numeric data type.


Using the keyboard to convert Korean characters to Chinese characters causes BizTalk Editor to fail

International Issue

Converting Korean characters to Chinese characters by using the CHINESE key on a Korean keyboard causes BizTalk Editor to fail. However, you can enter Chinese characters directly (for example, by copying a Chinese character from Notepad) into BizTalk Editor.


Cannot open BizTalk Editor or BizTalk Mapper

Cause: While using the XML parser, you are not able to open BizTalk Editor or BizTalk Mapper.

Solution: It is highly recommended that you use the Microsoft XML (MSXML) Parser version 3.0 with your installation of BizTalk Server 2002. In addition, it is recommended that you use the MSXML parser in Side-by-Side Mode. If you configure the MSXML parser to operate in Replace Mode by installing XMLINST.exe, you might experience problems with BizTalk Server. If you configure the MSXML parser to operate in Replace Mode by using XMLINST.EXE or by changing registry keys, your installation of BizTalk Server will not be supported.

The following procedure describes how you can configure the MSXML parser to operate in Side-by-Side Mode, if you currently have it configured to operate in Replace Mode.

  1. On the Start menu, click Run.

  2. In the Open box, type cmd and click OK.

  3. At the command prompt, type xmlinst -u and press ENTER.

  4. At the command prompt, type %WINDIR%\system32\regsvr32 msxml.dll and press ENTER.

  5. At the command prompt, type %WINDIR%\system32\regsvr32 msxml2.dll and press ENTER.

  6. At the command prompt, type %WINDIR%\system32\regsvr32 msxml3.dll and press ENTER.

  7. At the command prompt, type exit and press ENTER.

For more information about using XMLINST.exe, see the following article in the Microsoft Knowledge Base, "PRB: Application Errors Occur After You Run Xmlinst.exe on Production Servers" (support.microsoft.com/support/kb/articles/Q302/5/12.asp).


Integrating BizTalk Services

Integrating Microsoft® BizTalk™ Orchestration Services and BizTalk Messaging Services enables you to control the exchange of documents and messages between your trading partners and internal applications using multiple transport services. It also provides:

  • Control over complex, long-running transactions and business processes.

  • Reliable delivery of documents and messages.

  • Data validation by verifying each document instance against a specification.

  • Data mapping by using maps to transform document structure and format.

  • Data security and integrity by using encryption and digital signature certificates.

  • Support for receipt generation and correlation.

While there are many ways to integrate BizTalk Orchestration Services and BizTalk Messaging Services, this section presents a common scenario.

In this scenario, you configure an XLANG schedule instance on the source system to initiate and send a message to a destination system of a trading partner, wait to receive a return message from that partner, and then deliver that return message to the same XLANG schedule instance that sent the initial message. One example of a common business process where you might apply this configuration is for sending a purchase order and waiting to receive a purchase order receipt before continuing the process.

The topics in this section explain the configuration steps required for exchanging messages between your business and a trading partner by using a Hypertext Transfer Protocol (HTTP) transport and a non-HTTP transport. However, you can use a similar configuration to control the exchange of messages between applications within your business.

Because Microsoft BizTalk Server 2002 can serve either as the source system, which sends the initial message, or the destination system, which sends the return message, this section provides the configuration steps required for both. This also enables you to see the entire configuration that is required.

For samples of XLANG schedules that reflect these configurations and other related files, browse to the \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Integrating BizTalk Services folder.

Notes

  • The term messaging port, which is used in BizTalk Messaging Services, and the term port, which is used in BizTalk Orchestration Services, have entirely different meanings:
    • A messaging port is a set of properties that directs BizTalk Messaging Services to transport documents to a specified destination by using a specified transport service.

    • A port is a named location that uses a specific implementation. In an XLANG schedule, ports facilitate synchronous and asynchronous communications and are used to pass messages into or out of the schedule.
  • Action events related to messages processed by an XLANG schedule that are either sent to or received from BizTalk Messaging Services can be tracked in the Tracking database. For more information, see Tracking XLANG schedule Events in the Tracking Database.

The following topics are covered in this section:

  • Using an HTTP Transport

  • Using a Non-HTTP Transport

Related Topics

How Does BizTalk Server Work?

Instance Management


Using an HTTP Transport

This section explains how to integrate and configure BizTalk Orchestration Services and BizTalk Messaging Services for both the source system and destination system so that:

  • The source system generates and sends a message to the destination system of a trading partner by using a specific XLANG schedule instance.

  • The destination system sends a return message by using an HTTP transport.

  • The source system receives the return message and routes it to the same XLANG schedule instance that generated and sent the initial message.

To configure both systems so that the destination system can use a non-HTTP transport to send return messages, see Using a Non-HTTP Transport.

The following topics are covered in this section:

  • Configuring the Source System to Use an HTTP Transport

  • Configuring the Destination System to Use an HTTP Transport


Configuring the Source System to Use an HTTP Transport

The steps in this topic explain how to configure the source system to generate and send a message that contains an HTTP URL reply-to address. The destination system of the trading partner uses the reply-to address contained in the initial message to send a return message to an ASP page on the Web site of the source system by using an HTTP transport. If you want to configure the source system so that the destination system can use a non-HTTP transport to send return messages, see Configuring the Source System to Use a Non-HTTP Transport. The configuration steps required for using a Secure Hypertext Transfer Protocol (HTTPS) transport are discussed later in this topic.

The HTTP URL that is used as the reply-to address in this configuration is generated by the XLANG schedule based on data from the port properties. It is comprised of the following elements:

  • The address of an ASP page on the Web site of the source system to which a return message is sent.

  • A query string that contains the name of the channel in BizTalk Messaging Services for the source system that is used to process the return message, and a fully qualified path of a per-instance queue that the XLANG schedule instance creates and to which the return message is delivered.

The following is an example of an HTTP URL reply-to address:

http://hostname/receiveresponse.asp?channel=ChannelForReply&qpath=hostname.domain.corp.vigorair-18.com\private$\ChannelForReply{9e0016bf-be1f-48fe-82de-b27077ab5e73}

When the ASP page on the source system receives the return message, it contains script that performs the following steps:

  • Extracts the channel name and queue path information from the query string.

  • Converts the queue path from a path name to a format name, and inserts a queue:// prefix, which is required by BizTalk Messaging Services.

  • Submits the return message to BizTalk Messaging Services for the source system using the channel name and queue path information as submission parameters. For more information about submitting documents, see Submitting.

BizTalk Messaging Services for the source system uses the specified channel to process the return message and uses the associated messaging port, which uses the queue path to transport the return message to the same running XLANG schedule instance that generated the initial message.

For this source system configuration to work correctly, the destination system of the trading partner also must be correctly configured. For information about configuring the destination system, see Configuring the Destination System to Use an HTTP Transport.

To configure the source system to use an HTTP transport, complete the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications that are needed for the inbound and outbound document definitions of the channel that will process the initial message.
  • Create and Validate Specifications

    Note

    • You must add a field in each of these specifications for the reply-to address. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the destination system of your trading partner. For more information, see Manage Records and Fields.
  • Create the specifications that are needed for the inbound and outbound document definitions of the channel that will process the return message.
  • Create and Validate Specifications

    Note

    • These specifications do not require special configuration.
Using BizTalk Messaging Manager:
  • Create an organization to represent the trading partner and the destination system.
  • Create organizations

    Note

    • This organization does not require special configuration.
  • Create the document definitions needed to create the channel that you use to process the initial message.
  • Create document definitions

    Note

    • In the document definitions, select the specifications that have the reply-to field. For more information, see Select a document specification.
  • Create the document definitions needed to create the channel that you use to process the return message.
  • Create document definitions

    Note

    • These document definitions do not require special configuration.
  • Create a messaging port to an organization to transport the initial message to the destination system.
  • Create messaging ports

    Note

    • This messaging port cannot be an open messaging port.
  • Create a channel from an application to process the outbound message from the XLANG schedule.
  • Create channels

    Notes

    • On the Source Application page of the Channel Wizard, click XLANG schedule. For more information, see Set source application properties.

    • Make a note of the channel name and the inbound document definition name. These names are used to configure BizTalk Orchestration Services.
  • Create a messaging port to an application to transport the return message to the active XLANG schedule instance that generated the outbound message.
  • Create messaging ports

    Note

    • On the Destination Application page of the Messaging Port Wizard, click Running XLANG schedule. For more information, see Set destination application properties.
  • Create a channel from an organization to process the return message from the destination system.
  • Create channels

    Note

    • Make a note of the channel name and the outbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
Using BizTalk Orchestration Designer:
  • Use a BizTalk Messaging shape to implement a port to send the initial message.
  • Implement a port by using BizTalk Messaging

    Note

    • On the Static or Dynamic Channel Information page of the BizTalk Messaging Binding Wizard, click Static channel and, in the Enter the name of a known, pre-existing channel box, type the name of the channel in BizTalk Messaging Manager that you use to process the initial message.
  • Establish the communication flow between an Action shape and the port that sends the initial message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the inbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, type the name of the inbound document definition for the channel that you use to process the message.

    • On the Message Specification Information page, click Browse and browse to the specification that you use for the inbound document definition of the channel that you use to process the initial message.

    • On the Message Specification Information page, in the Message fields area, click Add and add the field in the specification that was created to contain the reply-to address in the initial message.
  • Use a BizTalk Messaging shape to implement a port where you receive a return message.
  • Implement a port by using BizTalk Messaging

    Notes

    • On the XLANG Schedule Activation Information page of the BizTalk Messaging Binding Wizard, click No.

    • On the Channel Information page, in the Channel name box, type the name of the channel in BizTalk Messaging Manager that you use to process the return message.

      BizTalk Orchestration Designer uses the channel name and a GUID to create and name a per-instance queue to which the return message is delivered.

    • On the Channel Information page, in the HTTP URL address where the BizTalk Messaging Service receives documents box, type the address of the ASP page where the trading partner can send a return message.

      BizTalk Orchestration Designer uses the address and the channel name that you entered previously to create an HTTP URL address with a query string that includes the channel name and the queue path of the per-instance queue.
  • Establish the communication flow between an Action shape and the port where you receive a return message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the outbound document definition for the channel makes it more apparent which message you are receiving.

    • On the Message Type Information page, in the Message type box, type the name of the outbound document definition for the channel that you use to process the return message.

      All messages delivered from BizTalk Messaging Services to an XLANG schedule instance are sent to a message queue. The message label given to these messages is the name of the outbound document definition of the channel.
  • Establish the data flow for passing the port reference data to the reply-to address field.
  • Draw the flow between messages

    Notes

    • Click the Data tab.

    • On the Data page, in the Port References message, click the port reference for the port that will receive the return message. Then drag its control handle to the connection point of the reply-to address field in the initial message.

      This passes the port reference data into the reply-to address field of the outbound initial message. The port reference is an HTTP URL address of an ASP page, which includes a query string with a channel name and the queue path of the per-instance queue for the port.
Using the ASP page:
  • You can use the sample ASP page that is provided with BizTalk Server 2002, or configure an ASP page that uses the same script as the sample page.
 Notes
  • To use the sample ASP page, browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReceiveScripts on the installation drive to locate the ReceiveResponse.asp sample. Place this file in the appropriate directory for the Web site of the source system.

  • When the sample ASP page receives a return message, its script extracts the channel name and queue path from the query string in the address of the HTTP header. The ASP page also converts the queue path from a path name to a format name and inserts a queue:// prefix. The page then uses this data as parameters to submit the return message to BizTalk Messaging Services for the source system. For more information about submitting documents, see Submitting.

Using a secure HTTPS transport

If your business process requires a secure transport for exchanging messages with a trading partner, you must use an HTTPS transport.

The only change that you need to make in the source system configuration to use an HTTPS transport is to modify the URL address for the port where you receive the return message.

When you implement the port that receives the return message, the URL that you enter for the reply-to address must use an HTTPS prefix, rather than an HTTP prefix.

The following is an example of a reply-to address that uses HTTPS:

https://hostname/receiveresponse.asp?channel=ChannelForReply&qpath=hostname.domain.corp.vigorair-18.com\private$\ChannelForReply{9e0016bf-be1f-48fe-82de-b27077ab5e73}

The destination system does not require any additional configuration changes.

Related Topic

Integrating BizTalk Services


Configuring the Destination System to Use an HTTP Transport

The steps in this topic explain how to configure the destination system to receive a message that contains an HTTP URL reply-to address and send a return message to the source system by using an HTTP transport. If you want to configure the destination system to use a non-HTTP transport to send return messages, see Configuring the Destination System to Use a Non-HTTP Transport. The configuration considerations for using an HTTPS transport are discussed later in this topic.

When BizTalk Messaging Services for the destination system receives the initial message, it is configured to activate a new instance of a specified XLANG schedule and send the message to a specified port in that XLANG schedule instance.

The XLANG schedule is configured to pass the reply-to address data that is contained in a field of the initial message to the port reference field for the port that is used to send the return message. The XLANG schedule then submits the return message to BizTalk Messaging Services using the Dynamic channel option.

For the Dynamic channel option, specific port data is passed as submission parameters when the message is submitted to BizTalk Messaging Services. The port reference data, in this case the reply-to address, is passed as the destination identifier parameter, and the Message type for the port is passed as the document definition name parameter. For more information about submission parameters, see Submitting. The submission parameters enable BizTalk Messaging Services to identify a specific channel to process the return message. For more information, see Identification.

When you use the Dynamic channel option, the channel in BizTalk Messaging Services must be associated with an open messaging port. The open messaging port transports the return message to the source system of the trading partner by using the reply-to address, which is passed as the destination identifier parameter. Because this is the HTTP URL of an ASP page on the source system, the HTTP transport is used. For more information about open messaging ports, see Open Messaging Ports.

For this destination system configuration to work correctly, the source system of the trading partner also must be correctly configured. For information about configuring the source system, see Configuring the Source System to Use an HTTP Transport.

To configure the destination system to use an HTTP transport, complete the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications for the inbound and outbound document definitions of the channel that you use to process the initial message.
  • Create and Validate Specifications

    Note

    • You must add a field in each of these specifications for the reply-to address. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the source system of your trading partner. For more information, see Manage Records and Fields.
  • Create the specifications that are needed for the inbound and outbound document definitions of the channel that will process the return message.
  • Create and Validate Specifications

    Note

    • These specifications do not require special configuration.
Using BizTalk Messaging Manager:
  • Create an organization to represent the trading partner with the source system.
  • Create organizations

    Note

    • This organization does not require special configuration.
  • Create the document definitions needed for creating a channel to process the initial message and a channel to process the return message.
  • Create document definitions

    Note

    • In the document definitions, select the previously created specifications. For more information, see Select a document specification.
  • Create a messaging port to an application to activate a new XLANG schedule instance, and transport the initial message to a port in that XLANG schedule instance.
  • Create messaging ports

    Notes

    • On the Destination Application page of the Messaging Port Wizard, click New XLANG schedule.

    • In the Schedule moniker box, type the moniker of the specified schedule or click Browse to set the path.

    • In the Port name box, type the name of the specific port in this schedule to which the document is sent.

      For more information, see Set destination application properties.
  • Create a channel from an organization to process the initial message from the trading partner.
  • Create channels

    Note

    • Make a note of the channel name and the outbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
  • Create an open messaging port to an organization to transport the return message to the source system.
  • Create messaging ports

    Note

    • On the Destination Organization page of the Messaging Port Wizard, click Open destination. For more information, see Set destination organization properties.

      An open messaging port requires that the destination information be contained in the document or provided by submission parameters. When the XLANG schedule submits the return message to BizTalk Messaging Services, it passes the reply-to address data, which was contained in the initial message, as the destination identifier submission parameter.
  • Create a channel from an application to process the return message from the XLANG schedule.
  • Create channels

    Note

    • On the Source Application page of the Channel Wizard, click XLANG schedule. For more information, see Set source application properties.
Using BizTalk Orchestration Designer:
  • Use a BizTalk Messaging shape to implement a port to receive the initial message.
  • Implement a port by using BizTalk Messaging

    Notes

    • On the Communication Direction page of the BizTalk Messaging Binding Wizard, click Receive.

    • On the XLANG Schedule Activation Information page of the BizTalk Messaging Binding Wizard, click Yes.

    Important

    • Choosing Yes configures the port to activate a new schedule instance when a message arrives. For important information about using this option, see the topic referenced for this step.
  • Establish the communication flow between an Action shape and the port that receives the initial message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the outbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, type the name of the outbound document definition for the channel that you use to process the return message.

      All messages passed from BizTalk Messaging to an XLANG schedule use a message queue. The label for these messages is the name of the outbound document definition of the channel.
  • Use a BizTalk Messaging shape to implement a port to send the return message with a dynamic channel.
  • Implement a port by using BizTalk Messaging

    Notes

    • On the Static or Dynamic Channel Information page of the BizTalk Messaging Binding Wizard, click Dynamic channel.

    • When you create a port that uses a dynamic channel, the channel that BizTalk Messaging Services uses to process the message is determined by port data passed as submission parameters. This is described later in this table.
  • Establish the communication flow between an Action shape and the port that is used to send the return message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the inbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, you must type the name of the inbound document definition for the channel that you use to process the message.

      The inbound document definition data is passed as a submission parameter to BizTalk Messaging Services. This is described later in this table.
  • Establish the data flow to pass the reply-to address field to the port reference of the port that sends the return message.
  • Draw the flow between messages

    Notes

    • Click the Data tab.

    • On the Data page, in the initial message, click the reply-to address field. Then drag its control handle to the left connection point of the port reference in the Port References message for the port that is used to send the return message.

    Important

    • You must connect the reply-to address field to the left connection point of the port reference. A left connection point on a port reference is available only when a port is configured to use a dynamic channel to send messages.

      For a port that uses a dynamic channel, the data for the port reference must be passed from a field in a previously received message.

      In this scenario, the reply-to address data from the initial message is passed to the port reference field for the port that is used to send the return message. The reply-to address is the HTTP URL to where the return message is sent.

      When a port that uses a dynamic channel passes a message to BizTalk Messaging Services, the port reference data is passed as the destination identifier parameter and the message type data is passed as the document definition parameter. The parameters enable BizTalk Messaging Services to identify which channel to invoke to process the message. For more information, see Identification and Submitting.

      When a port is configured to use a dynamic channel, the destination information is passed as a parameter in an open destination submission. Therefore, any channel that is invoked by a port that uses a dynamic channel must be associated with an open messaging port.

Using a secure HTTPS transport

Because the messaging port that you use to transport return messages is an open messaging port, you cannot use an encryption certificate to encrypt documents.

If your business process requires a secure transport for exchanging messages with a trading partner, the source system must include an HTTPS URL as the reply-to address in the initial messages that are sent to you, rather than an HTTP URL.

For more information, see Configuring the Source System to Use an HTTP Transport.


Using a Non-HTTP Transport

This section explains how to integrate and configure BizTalk Orchestration Services and BizTalk Messaging Services for both the source system and destination system so that:

  • The source system generates and sends a message to the destination system of a trading partner by using a specific XLANG schedule instance.

  • The destination system receives the initial message, activates an XLANG schedule instance that generates a return message, and then sends the return message to the source system using a non-HTTP transport.

To configure both systems so that the destination system can use an HTTP transport to send return messages, see Using an HTTP Transport.

The following topics are covered in this section:

  • Configuring the Source System to Use a Non-HTTP Transport

  • Configuring the Destination System to Use a Non-HTTP Transport


Configuring the Source System to Use a Non-HTTP Transport

The steps in this topic explain how to configure the source system to generate and send a message that contains the path of a static queue. The destination system of the trading partner is configured to pass the queue path contained in the message into a field of a return message, and send it to the source system by using a non-HTTP transport. If you want to configure the source system so that the destination system can use an HTTP transport to send return messages, see Configuring the Source System to Use an HTTP Transport.

When the source system receives the return message, it submits the message to BizTalk Messaging Services. BizTalk Messaging Services transports the return message to the queue that is specified by the queue path contained in the document field. This queue is monitored by the same XLANG schedule instance that generated the initial message, and the schedule retrieves the return message from that queue.

For this source system configuration to work correctly, the destination system of the trading partner also must be correctly configured. For information about configuring the destination system, see Configuring the Destination System to Use a Non-HTTP Transport.

To configure the source system to use a non-HTTP transport, complete the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications for the inbound and outbound document definitions of the channel that you use to process the initial message.
  • Create and Validate Specifications

    Note

    • You must add a field in each of these specifications for the queue path. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the destination system of your trading partner. For more information, see Manage Records and Fields.
  • Create the specifications for the inbound and outbound document definitions of the channel that you use to process the return message.
  • Create and Validate Specifications

    Notes

    • You must add a field to the inbound specification for the queue path. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the destination system of your trading partner. For more information, see Manage Records and Fields.

    • The queue path field in the inbound specification must be set as the destination value in the dictionary properties. For more information, see Set dictionary properties.

      When the return message is received and submitted to BizTalk Messaging Services on the source system, the queue path field is recognized and treated as the destination identifier parameter. For more information, see Submitting. The messaging port transports the return message to the queue specified by this queue path. The XLANG schedule monitors this queue and retrieves the return message.

Using BizTalk Mapper:
  • Create a map to be used in the channel that processes the initial message.
  • Create new maps

    Important

    • The syntax for the queue path name that the XLANG schedule generates must be changed from a path name to a format name and have the queue:// prefix added. For the HTTP transport scenario, the script in the ASP page makes this change. To make this change for the non-HTTP transport scenario, you must use a Concatenate functoid in a map. For more information, see Integrating BizTalk Services Using Maps.
Using BizTalk Messaging Manager:
  • Create an organization to represent the trading partner with the destination system.
  • Create organizations

    Note

    • This organization does not require special configuration.
  • Create the document definitions needed to create a channel to process the initial message and a channel to process the return message.
  • Create document definitions

    Note

    • In the document definitions, select the previously created specifications. For more information, see Select a document specification.
  • Create a messaging port to an organization to transport the initial message to the destination system.
  • Create messaging ports

    Note

    • This messaging port does not require special configuration.
  • Create a channel from an application to process the initial message from the XLANG schedule.
  • Create channels

    Notes

    • On the Source Application page of the Channel Wizard, click XLANG schedule. For more information, see Set source application properties.

    • On the Outbound Document page, select the Map inbound document to outbound document check box and, to the right of the Map reference box, click Browse. Then browse to the map that you created previously and click Open.

    • Make a note of the channel name and the inbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
  • Create an open messaging port to an organization to transport the return message to the active XLANG schedule instance that generated the initial message.
  • Create messaging ports

    Notes

    • On the Destination Organization page of the Messaging Port Wizard, click Open destination. For more information, see Set destination organization properties.

    • For this scenario, you create a messaging port to an organization, even though you send the return message to an application, an XLANG schedule.

      This enables you to use an open messaging port to submit the return message using the queue path information as a submission parameter. For more information, see Submitting.

      The open messaging port transports the return message to the static queue that is specified in the queue path, where the XLANG schedule is configured to retrieve it.
  • Create a channel from an organization to process the return message from the destination system.
  • Create channels

    Notes

    • The inbound document definition for this channel must use the document definition that uses the previously created specification in which you designated the queue path field as the destination value in the dictionary properties.

    • Make a note of the channel name and the inbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
Using BizTalk Orchestration Designer:
  • Use a BizTalk Messaging shape to implement a port to send the initial message.
  • Implement a port by using BizTalk Messaging

    Note

    • On the Static or Dynamic Channel Information page of the BizTalk Messaging Binding Wizard, click Static channel and, in the Enter the name of a known, pre-existing channel box, type the name of the channel in BizTalk Messaging Manager that you use to process the initial message.
  • Establish the communication flow between an Action shape and the port that sends the initial message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the inbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, type the name of the inbound document definition for the channel that you use to process the message.

    • On the Message Specification Information page, click Browse and browse to the specification that you use for the inbound document definition of the channel for the initial message.

    • On the Message Specification Information page, in the Message fields area, click Add and add the field in the specification that was created to contain the queue path.
  • Use a Message Queuing shape to implement a port where you receive a return message.
  • Implement a port by using Message Queuing

    Notes

    • In this scenario, you use a Message Queuing port binding, even though you are receiving a message from BizTalk Messaging Services.

    • On the Static or Dynamic Queue Information page of the Message Queuing Binding Wizard, click Static queue.

    • On the Queue Information page, click Create a new queue for every instance, and, in the Enter the queue prefix box, type the name of the prefix that will be used to create the queue name.
  • Establish the communication flow between an Action shape and the port where you receive a return message.
  • Send or receive asynchronous messages

    Notes

    • On the Welcome to the XML Communication Wizard page of the XML Communication Wizard, click Receive.

    • On the Message Information page, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the outbound document definition for the channel makes it more apparent which message you are receiving.

    • On the Message Type Information page, in the Message type box, type the name of the outbound document definition for the channel that you use to process the return message.

      All messages passed from BizTalk Messaging to an XLANG schedule use a message queue. The label for these messages is the name of the outbound document definition of the channel.
  • Establish the data flow from the receiving port reference to the queue path field.
  • Draw the flow between messages

    Notes

    • Click the Data tab.

    • On the Data page, in the Port References message, click the field for the port that receives the return message. Then drag its control handle to the connection point of the queue path field in the initial message.

      This inserts the port reference data into the queue path field of the initial message. The port reference is the queue path of the static queue for the port that you use to receive a return message.


Configuring the Destination System to Use a Non-HTTP Transport

The steps in this topic explain how to configure the destination system to receive a message that contains a queue path and to send a return message that contains the same queue path to the source system by using a non-HTTP transport. If you want to configure the destination system to use an HTTP transport to send return messages, see Configuring the Destination System to Use an HTTP Transport.

When BizTalk Messaging Services for the destination system receives the initial message, it is configured to activate a new instance of a specified XLANG schedule and pass the message to a specified port in that XLANG schedule instance.

The XLANG schedule is configured to pass the data contained in the queue path field of the initial message into a matching field of the return message, and then submit the return message to a channel in BizTalk Messaging Services.

BizTalk Messaging Services uses the specified channel to process the return message and pass it to a messaging port. This messaging port is configured to transport the return message to an address that is agreed upon with the trading partner with the source system. This messaging port cannot be an open messaging port.

For this destination system configuration to work correctly, the source system of the trading partner also must be correctly configured. For information about configuring the source system, see Configuring the Source System to Use a Non-HTTP Transport.

To configure the destination system to use a non-HTTP transport, complete the steps in the following table. References are provided for each procedure, and notes are provided to indicate special configuration considerations. Other property settings needed to complete the configuration vary according to your particular business situation and are not specified here.

Step References and notes
Using BizTalk Editor:
  • Create the specifications for the inbound and outbound document definitions of the channel that you use to process the initial message.
  • Create and Validate Specifications

    Note

    • You must add a field in each of these specifications for the queue path. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the source system of your trading partner. For more information, see Manage Records and Fields.
  • Create the specifications for the inbound and outbound document definitions of the channel that you use to process the return message.
  • Create and Validate Specifications

    Note

    • You must add a field in each of these specifications for the queue path. This field can be added at any level; however, the location must be agreed upon with the trading partner and match the specifications on the source system of your trading partner. For more information, see Manage Records and Fields.
Using BizTalk Messaging Manager:
  • Create an organization to represent the trading partner with the source system.
  • Create organizations

    Note

    • This organization does not require special configuration.
  • Create the document definitions needed for creating a channel to process the initial message.
  • Create document definitions

    Note

    • In the document definitions, select the previously created specifications. For more information, see Select a document specification.
  • Create the document definitions needed for creating a channel to process the return message.
  • Create document definitions

    Note

    • In the document definitions, select the previously created specifications. For more information, see Select a document specification.
  • Create a messaging port to an application to activate a new XLANG schedule instance, and transport the initial message to a port in that XLANG schedule instance.
  • Create messaging ports

    Notes

    • On the Destination Application page of the Messaging Port Wizard, click New XLANG schedule.

    • In the Schedule moniker box, type the moniker of the specified schedule or click Browse to set the path.

    • In the Port name box, type the name of the specific port in this schedule to which the document is sent.

      For more information, see Set destination application properties.

      To complete this step, you need the path of an XLANG schedule and the name of the port in that schedule to which the initial message is delivered. Therefore, you must first create the XLANG schedule and configure its port, as described later in this table.
  • Create a channel from an organization to process the initial message from the trading partner.
  • Create channels

    Note

    • Make a note of the channel name and the outbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
  • Create a messaging port to an organization to transport the return message to the source system.
  • Create messaging ports

    Notes

    • On the Destination Organization page of the Messaging Port Wizard, click Organization. To the right of the Name box, click Browse.

    • In the Select an Organization dialog box, select the organization that you created previously to represent the trading partner with the source system. For more information, see Select a destination organization.

    • On the Destination Organization page of the Messaging Port Wizard, in the Primary Transport area, click Browse.

    • In the Primary Transport dialog box, in the Transport type list, select the transport type and, in the Address box, type an address.

      The transport type and address must be agreed upon with the trading partner and match the specifications on the source system of your trading partner.

    • You cannot use an open messaging port to send the return message.
  • Create a channel from an application to process the return message from the XLANG schedule.
  • Create channels

    Notes

    • On the Source Application page of the Channel Wizard, click XLANG schedule. For more information, see Set source application properties.

    • Make a note of the channel name and the inbound document definition name that you use. These names are used to configure BizTalk Orchestration Services.
Using BizTalk Orchestration Designer:
  • Use a BizTalk Messaging shape to implement a port to receive the initial message.
  • Implement a port by using BizTalk Messaging

    Notes

    • On the Communication Direction page of the BizTalk Messaging Binding Wizard, click Receive.

    • On the XLANG Schedule Activation Information page of the BizTalk Messaging Binding Wizard, click Yes.

    Important

    • Choosing Yes configures the port to activate a new schedule instance when a message arrives. For important information about using this option, see the topic referenced for this step.

      Make a note of the name that you give to this port and the location to which you save the compiled XLANG schedule. You need this information to configure a messaging port in BizTalk Messaging Services, as described previously in this table.
  • Establish the communication flow between an Action shape and the port that receives the initial message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the outbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, type the name of the outbound document definition for the channel that you use to process the return message.

      All messages passed from BizTalk Messaging to an XLANG schedule use a message queue. The label for these messages is the name of the outbound document definition of the channel.

    • On the Message Specification Information page, click Browse and browse to the specification that you use for the outbound document definition of the channel for the initial message.

    • In the Message fields area, click Add and add the field in the specification that was created to contain the queue path address for the initial message.
  • Use a BizTalk Messaging shape to implement a port to send the return message.
  • Implement a port by using BizTalk Messaging

    Notes

    • On the Static or Dynamic Channel Information page of the BizTalk Messaging Binding Wizard, click Static channel and, in the Enter the name of a known, pre-existing channel box, type the name of the channel in BizTalk Messaging Manager that you use to process the return message.

    • Because this port uses a static channel, an open destination submission call to BizTalk Messaging is not made. Therefore, the channel that is specified cannot be associated with an open messaging port.
  • Establish the communication flow between an Action shape and the port that sends the return message.
  • Send or receive asynchronous messages

    Notes

    • On the Message Information page of the XML Communication Wizard, click Create a new message and, in the Message name box, type a name for the message.

      You can use any name; however, using the name of the inbound document definition for the channel makes it more apparent which message you are sending.

    • On the Message Type Information page, in the Message type box, type the name of the inbound document definition for the channel that you use to process the message.

    • On the Message Specification Information page, click Browse and browse to the specification that you use for the inbound document definition of the channel that you use to process the return message.

    • In the Message fields area, click Add and add the field in the specification that was created to contain the queue path address for the return message.
  • Establish the data flow for the queue path field in the initial message to the queue path field in the return message.
  • Draw the flow between messages

    Notes

    • Click the Data tab.

    • On the Data page, click the queue path field in the initial message. Then drag its control handle to the connection point of the queue path field in the return message.

      This passes the queue path data from the initial message into the return message.


BizTalk Server 2002 Developer Solutions

You can programmatically integrate applications with Microsoft® BizTalk™ Server 2002 by using the BizTalk Messaging Configuration object model, or by extending and customizing the functionality of the server to suit your business and information-exchange needs. The developer solutions provide all the information necessary for Microsoft Visual Basic® and C++ developers to use or extend BizTalk Server 2002. This section also includes a complete list of interfaces, objects, enumerations, code samples, and possible error messages.

BizTalk Server 2002 supports programmatic application integration by accessing the BizTalk Messaging Configuration object model and submitting documents by calling the methods of the IInterchange interface. BizTalk Server 2002 also supports the use of extensible application integration components (AICs), including a lightweight integration model and support for the pipeline-component model available in Microsoft Site Server 3.0, Commerce Edition.

Developer Solutions is divided into the following sections:

BizTalk Messaging Services

This section provides information about how to access the BizTalk Messaging Configuration object model, including all the reference pages for the supported interfaces. This information is provided for both C++ and Visual Basic developers. For more information, see BizTalk Messaging Services.

BizTalk Documents

This section covers submitting documents to BizTalk Server 2002, using the synchronous and asynchronous methods of the IInterchange interface. It shows how to move a document after the trading partner relationships are set up, and how to track documents moving through BizTalk Server 2002. For more information, see BizTalk Documents.

BizTalk Custom Components

This section covers BizTalk Server 2002 support for extensible application integration components (AICs), including a lightweight integration model and support for the pipeline-component model available in Microsoft Site Server 3.0, Commerce Edition.

This allows developers to do the following:

  • Enable business applications to receive business documents by using AICs.

  • Extend the functionality of BizTalk Server 2002 by developing components to perform digital signatures and verification, encryption and decryption, parsing, and transport.

For more information, see BizTalk Custom Components.

BizTalk Orchestration Services

This section provides information about the interfaces that can be used to access a running instance of a specific XLANG schedule, or to perform system-wide administrative tasks in the XLANG Scheduler run-time environment. This information is provided for both C++ and Visual Basic developers. For more information, see BizTalk Orchestration Services.

BizTalk Managing and Monitoring

This section covers the Windows Management Instrumentation (WMI) classes that allow you to perform administrative functions that support the management of systems in an enterprise. This information is provided for C++, Visual Basic, and Visual Basic Scripting Edition (VBScript) developers. For more information, see BizTalk Managing and Monitoring.

BizTalk Server Developer's Toolbox

This section provides code solutions to problems commonly encountered by developers working with BizTalk Server. For more information, see BizTalk Server Developer's Toolbox.

BizTalk Server Samples

This section provides documentation and instructions for running the samples included in the BizTalk Server SDK. For more information, see BizTalk Server Samples.

BizTalk Server Reference

This section documents the BizTalk Server application programming interfaces (APIs) and error messages. For more information, see BizTalk Server Reference.


BizTalk Messaging Services

This section provides information about how to access the BizTalk Messaging Configuration object model programmatically. It shows how to manage trading partner relationships and set up messaging ports and channels for the exchange of data, using Microsoft® BizTalk™ Server 2002. This section also shows how to create document definitions and envelopes, and how to set organization properties. For additional information, see the following sections:

  • For introductory information about the BizTalk Messaging Configuration object model, see Introducing Messaging Services.

  • For general background information, see Understanding Messaging Services.

  • For information about COM interfaces, enumerations, and error messages, see the Messaging Services Reference.

  • For examples of code, see BizTalk Messaging Services Code Samples.

The BizTalk Messaging Configuration object model can also be configured by using the BizTalk Messaging Manager graphical user interface. For more information, see Using BizTalk Messaging Manager.


Introducing Messaging Services

The BizTalk Messaging Configuration object model provides an easy way for applications to set up, maintain, and retrieve messaging ports and channels for trading partner relationships and application-to-application integration. The BizTalk Messaging Configuration object model can also create envelopes and document definitions, and set organization properties.

The BizTalk Messaging Configuration object model uses a Structured Query Language (SQL) database to store the port configurations and other relational data. ActiveX® Data Objects (ADO) recordsets are returned when querying for lists of object instances (for example, messaging ports or organizations).

The BizTalk Messaging Configuration object model consists of Component Object Model (COM) objects that expose the configuration data required for Microsoft BizTalk Server 2002 to configure the interchange of structured documents between applications and trading partners. The COM objects represent instances of data in memory that can be stored in the database.

All object properties are read/write, except where noted.

Related Topics

Messaging Configuration Objects

Referential Integrity

Security


Messaging Configuration Objects

The following table shows the objects of the BizTalk Messaging Configuration object model.

Object | Description
IBizTalkChannel | Contains the configuration related to the source entity and its binding with an IBizTalkPort object.
IBizTalkConfig | Creates and retrieves other BizTalk objects, such as channels, document specifications, and messaging ports.
IBizTalkDocument | Identifies and describes the specification of a document.
IBizTalkEnvelope | Identifies the envelope format and/or the envelope schema used for documents. Envelopes are required for documents using the X12 or EDIFACT format.
IBizTalkOrganization | Identifies the source or destination point for the exchange of electronic data. An organization can represent an external trading partner, your own company, or a business unit of a trading partner or your company. An organization can designate a source application in a channel or a destination application in a port.
IBizTalkPort | Defines the destination-related attributes of a document submission.
IBizTalkPortGroup | Configures a port group. This is a group of complete IBizTalkPort objects for sending the same document, such as a catalog, a price list, or a newsletter, to a group of trading partners.

Caution

  • Do not access the database directly. Do not directly call the stored procedures. Make all changes to the database by using the methods and properties of the BizTalk Messaging Configuration object model. Making changes to the database directly bypasses many constraints enforced by the BizTalk Messaging Configuration object model and either causes the server to function incorrectly or corrupts the database.

  • The BizTalk Messaging Configuration object model should be accessed only at design time. Accessing objects in use while BizTalk Server is processing documents can produce unexpected results.

  • BizTalk Server 2002 treats all variables with a BSTR data type as NULL-terminated strings. Any data contained in a BSTR after the NULL character is ignored. Documents containing embedded NULL characters must be submitted to BizTalk Server by using pass-through mode.

Related Topics

Channels

Document Definitions

Envelopes

Messaging Ports

Organizations


Referential Integrity

Referential dependency must be considered when instantiating objects in BizTalk Server 2002. Referential dependency indicates that one object refers to, and is dependent upon, another object. For example, an IBizTalkChannel object refers to an IBizTalkPort object.

To maintain referential integrity, an object instance cannot be deleted if it is referred to by another object instance. Referential integrity is maintained when the object that is referred to exists in the database.

Remove objects from the database in the reverse order of their creation. If an object instance that is referred to by another object instance is removed, a constraint error is returned. Using the preceding example, a constraint error is returned if an IBizTalkPort object that is being used by an IBizTalkChannel object is removed.

The following sequence shows the preferred order for creating objects to maintain the referential integrity of the objects:

  1. IBizTalkOrganization

  2. IBizTalkDocument

  3. IBizTalkEnvelope (if required)

  4. IBizTalkPort
    • The IBizTalkPort object requires the IBizTalkOrganization object.

    • The IBizTalkPort object conditionally uses the IBizTalkEnvelope object.
  5. IBizTalkChannel
    • The IBizTalkChannel object requires the IBizTalkPort object.

    • The IBizTalkChannel object requires the IBizTalkDocument object.

    • The IBizTalkChannel object requires the IBizTalkOrganization object.

    • The IBizTalkChannel object conditionally uses the IBizTalkPortGroup object if the channel is created for port groups.
  6. IBizTalkPortGroup (if used)
    • The IBizTalkPortGroup object requires the IBizTalkPort object.


Security

When accessing or creating objects in the BizTalk Messaging Configuration object model, the script or application must be run in the context of a user account in the BizTalk Server Administrators group. The BizTalk Server Administrators group is created when BizTalk Server 2002 is installed. Additional users can be added to this group as necessary. For additional information, see Add users to the BizTalk Server Administrators group.


Understanding Messaging Services

This section provides detailed conceptual information that is important to understanding how to access the BizTalk Messaging Configuration object model. The following topics are covered in this section:

  • Channels

  • Messaging Ports

  • Openness

  • Organizations

  • Document Definitions

  • Envelopes

  • Certificates

For information about code samples that use the BizTalk Messaging Configuration object model, see BizTalk Messaging Services Code Samples.


Channels

The IBizTalkChannel object contains the configuration information related to the source entity and its binding with an IBizTalkPort object. When BizTalk Server 2002 receives a document, a specific IBizTalkChannel object, along with the properties configured in its associated IBizTalkPort object or an associated IBizTalkPort object within an IBizTalkPortGroup, directs the server through the steps necessary to process that document. Note that multiple channels might be bound to the same IBizTalkPort object. This represents multiple source entities that exchange documents with the same destination.

The IBizTalkChannel object identifies the map used for document transformation if the type of the input IBizTalkDocument object is different from the type of the output IBizTalkDocument object. It also points to the specification that contains fields for BizTalk document tracking and selects the type of logging desired.

The following topics are covered in this section:

  • Identification

  • Document Processing

  • Configuring

  • Channel Filtering

  • Document Storage

  • Document Tracking


Identification

BizTalk Server 2002 determines the appropriate IBizTalkChannel object for processing the input document by one of the following methods:

  • The source organization identifier, qualifier, and value; the destination organization identifier, qualifier, and value; and the name of the IBizTalkDocument object are parameters of the Submit or the SubmitSync method of the IInterchange object.

  • The source and destination organization identifiers, qualifiers, and values; and the name of the IBizTalkDocument object are specified in the header fields of the document instance.

  • The name of the IBizTalkChannel object is a parameter of the Submit or the SubmitSync method call.

When BizTalk Server 2002 receives a document, it first identifies all IBizTalkChannel objects that support the specified IBizTalkDocument object. The server then looks up each IBizTalkPort object and determines if the source organization and destination organization properties identify the source and destination IBizTalkOrganization objects specified by the organization identifiers in the document or in the parameters of Submit when the document is submitted. This includes any open messaging ports that match either the specified source organization or the destination organization.

This identification process can be bypassed by specifying the name of an IBizTalkChannel object to be used as a parameter of Submit or SubmitSync.

Related Topic

Submitting


Document Processing

When BizTalk Server 2002 identifies an IBizTalkChannel object, the server processes this object, which directs the server in the steps to process the document. To direct the server, the IBizTalkChannel object follows its own rules and the rules of its associated IBizTalkPort object.

An input IBizTalkDocument object is related to an output IBizTalkDocument object by an IBizTalkChannel object. The IBizTalkPort object must be created before an associated IBizTalkChannel object can be created.

When BizTalk Server 2002 processes an IBizTalkChannel object, the server calls upon each associated IBizTalkPort object to provide the document-processing rules needed by the server. The rules set by the properties of the IBizTalkChannel object direct the server in the initial steps of document processing, such as determining which input and output IBizTalkDocument objects to use, which map file to use, and what fields to track. After a document is in its final output format, the properties of the IBizTalkPort object direct the server in the steps to prepare and transport the document according to the rules agreed to by the source and destination organizations.

When a document is submitted, the server can identify multiple IBizTalkPort and IBizTalkChannel objects that match the source organization, the destination organization, and the specified IBizTalkDocument object. Therefore, it is possible for one input document to generate multiple output documents. It is also possible for each output document to be transmitted to a different location by using different transport properties in the matching IBizTalkPort objects, and for each output document instance to include a different subset of data from the original input document by using different map files.


Configuring

An IBizTalkChannel object consists of the internal document processing data for the specified input and output IBizTalkDocument objects. To be fully configured, an IBizTalkChannel object must have one complete IBizTalkPort object identified by its Port property. Input and output IBizTalkDocument objects must be specified. After the InputDocument and OutputDocument properties are selected for use in this IBizTalkChannel object, an IBizTalkPort object or an IBizTalkPortGroup object must be selected.

The name of an IBizTalkChannel object must be unique across the database for all objects of its type.

The following properties are required before an IBizTalkChannel object can be saved:

  • InputDocument

  • Port (or PortGroup)

  • OutputDocument

  • Name

After an IBizTalkChannel object has been created or saved, only the following properties can be changed:

  • Comments

  • ControlNumberValue

  • MapReference

  • Name

  • TrackFields


Channel Filtering

Channel filtering enables the user to build a filtering expression to select an IBizTalkChannel object for processing a document instance. The server uses these expressions to select the correct IBizTalkChannel object. The Expression property contains an XPath expression that evaluates to a Boolean value. If the expression evaluates to true, the channel is used to process the document. Otherwise, the channel is not invoked to process the document.

XPath expressions can be used to obtain the value of a specific element, attribute, or collection of these items within an XML document. Consider the following XML document:

<INVOICE>

<DATE>12/31/2000</DATE>

<BILLTO>Blue Yonder Airlines</BILLTO>

<SUMMARY>

<ITEM PARTNUMBER="10001" QUANTITY="10"/>

<ITEM PARTNUMBER="20002" QUANTITY="20"/>

<TOTAL VALUE="550"/>

</SUMMARY>

</INVOICE>

Based on this document, the following XPath expression can be created to ensure that this channel only processes invoices that exceed $500:

myChannel.Expression = "/INVOICE/SUMMARY/TOTAL[@VALUE>""500""]"

In this example, the channel would process the XML document instance because the total is greater than $500. For more information about XPath expressions, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and search for XPath.

Note

  • You can use BizTalk Messaging Manager to generate XPath channel filtering expressions. For more information, see Add a channel filtering expression.


Document Storage

You can choose how to log the activity of a document instance by using the IBizTalkLoggingInfo object. The default is to log the document in its native form.

For document storage, you have the options shown in the following table.

Property | Description
All properties empty | Store no copies of the document.
LogNativeInputDocument | Store input native format (default setting).
LogNativeOutputDocument | Store output native format.
LogXMLInputDocument | Store input XML format.
LogXMLOutputDocument | Store output interim (XML) format.
Any combination of these choices | Store the options as described above.

Note

  • There is a size limit for interchanges and documents that use logging, which if exceeded greatly affects the performance of BizTalk Server. For more information about the size limit, see Interchange and document size limit.


Document Tracking

An IBizTalkChannel object points to the specification that contains fields to track the instance of the document. The designated fields are logged to the Tracking database for each instance of a document that is processed. When you assign an input IBizTalkDocument object for an IBizTalkChannel object, you can designate fields to track within the document on this channel.

When BizTalk Server 2002 runs an IBizTalkChannel object, it uses the input IBizTalkDocument object to process an input document. The fields that you have designated for tracking are captured and logged for each instance of that document. Any fields designated for tracking in the output IBizTalkDocument object of the associated IBizTalkChannel object are ignored. To retrieve the information that is tracked during document processing, use the methods of the IBizTalkTrackData object.

By logging important data from the input documents that are processed, you can track and analyze detailed information about your operation. For example, an invoice-total field can be logged for every invoice that is sent to your trading partners. You can then determine the total dollar amount of invoices sent to all trading partners over time or determine the total dollar amount of invoices to each individual trading partner.

For additional information about document tracking, see Understanding the Tracking Database Schema.


Messaging Ports

Conceptually, a messaging port is a set of rules that trading partner organizations accept for sending documents to one another. It includes information regarding the destination, transport type, security, and envelope. It identifies the source and destination IBizTalkOrganization objects and the source and destination aliases. It also identifies any applications associated with the organization, if applicable.

An IBizTalkPort object identifies a specific destination organization unless it is designated as an open messaging port, in which case the destination organization is not specified. For open messaging ports, the IBizTalkPort object is valid only if the associated document or the parameters on the Submit or the SubmitSync method of the IInterchange object contain the destination transport and address information.

The IBizTalkPort object also identifies delimiter definitions and the EDI interchange control number. Delimiters are used to separate the records and fields of the envelope and the documents within the envelope. An interchange control number is used to identify and track documents that are sent using the envelope. The interchange control number is incremented with each use of the envelope at run time.

An IBizTalkPort object also identifies the encoding, encryption, and signature type, if required.

Note

  • After an IBizTalkPort object has been created and saved, the destination organization and the openness associated with the endpoint cannot be changed.

Related Topics

Openness

Port Groups


Port Groups

The IBizTalkPortGroup object configures a group of complete IBizTalkPort objects for sending the same document to a group of trading partners. For example, you can use this when you want to send a document, such as a catalog, a price list, or a newsletter, that contains identical data to a group of trading partners. One document is sent to a list of partners by calling a single Submit method on the IInterchange object.

The IBizTalkPortGroup object must contain at least one IBizTalkPort object. You can add or remove IBizTalkPort objects to or from an IBizTalkPortGroup by calling the AddPort or the RemovePort method.

An IBizTalkPortGroup object must be associated with at least one IBizTalkChannel object. After the port group has been created, associate a channel with the port group by using the PortGroup property available on the IBizTalkChannel object. When BizTalk Server 2002 invokes a channel related to a port group, it invokes only the channel that is associated with the port group to process the data. None of the channels that are associated with the individual ports in the port group are invoked. The server uses the properties of each port successively to transport the data to the destinations specified in the ports.

Notes

  • Open messaging ports cannot be added to a port group.

  • BizTalk Messaging Manager refers to port groups as distribution lists.

Related Topic

Submitting


Openness

The Openness property of the IBizTalkEndPoint object determines whether the messaging port or channel is open. An open IBizTalkPort object is a messaging port without a specified destination. An open IBizTalkChannel object is a channel without a specified source. The missing information for an open messaging port or channel must be supplied by the associated document or by the parameters on the Submit or the SubmitSync method of the IInterchange object.

If an open channel is specified by using BIZTALK_OPENNESS_TYPE_EX_SOURCE or an open messaging port is specified by using BIZTALK_OPENNESS_TYPE_EX_DESTINATION, the Usage, Reference, and Store properties cannot be specified on the IBizTalkCertificateInfo object.

Note

  • If an open messaging port is used with the SMTP transport type, the value specified for the IBizTalkOrganization identifier Reliable Messaging Acknowledgement SMTP From Address is used as the From address.

Related Topic

Submitting


Organizations

IBizTalkOrganization objects serve as sources or destinations for the exchange of electronic data. An organization can represent an external trading partner, your own company, or a business unit of a trading partner or your company. The home organization can designate a source application in a channel or a destination application in a messaging port.

Applications are properties of the home organization. An applications can be designated as a source application in an IBizTalkChannel object or as a destination application in an IBizTalkPort object.

Aliases

An alias is an organization identifier for the IBizTalkOrganization object. An IBizTalkOrganization object must always have one and only one default alias, but it can have multiple aliases. An alias is autogenerated for each IBizTalkOrganization object. The default alias and the autogenerated alias cannot be removed.

For more information, see Create and Manage Organizations.


Document Definitions

The IBizTalkDocument object describes and identifies the document specification used to describe the document sent or received. The document specification defines the structure of a document, as well as any validation rules and descriptions for the individual elements of the document specification. The IBizTalkDocument object includes the version and type of the specification and, optionally, a reference to the Web Distributed Authoring and Versioning (WebDAV) location of the specification. For more information about document specifications, see Create and Validate Specifications.

Notes

  • The document Content and NameSpace properties are not valid until you set the Reference property.

  • When creating a new IBizTalkDocument object that uses a namespace that is already registered with BizTalk Server, the new document inherits the Reference property of that namespace. The namespace must be unique (case insensitive) for a new Reference to be created.

The IBizTalkDocument object also contains the electronic data interchange (EDI) selection criteria by which BizTalk Server 2002 extracts information from the functional group header of the document to identify this object when the name of the IBizTalkDocument object is not available.

An IBizTalkDocument object points to the specification that contains fields to track the instance of the document. The designated fields are logged to the Tracking database for each document that is processed.

Selection criteria

For some EDI input interchanges, documents are contained within functional group envelopes. When BizTalk Server 2002 processes such documents, it cannot obtain the name of the IBizTalkDocument object from a field within each document. Also, because there are multiple types of documents involved, a single name cannot be specified as a parameter of the Submit method of the IInterchange object. In such cases, the server can locate document-related data within the functional group header (for example, in the GS header of an X12 interchange). By comparing this data to matching selection criteria specified in the PropertySet property on the IBizTalkDocument object, the server can uniquely identify an IBizTalkDocument object. After the IBizTalkDocument object is identified, the server can obtain the name and then identify and instantiate the appropriate IBizTalkChannel object.

Selection criteria also help BizTalk Server 2002 create the header of the EDI document when it is output.

Global tracking

An IBizTalkDocument object points to the specification from which fields can be selected for tracking. The designated fields in the input document specification are tracked for each document that is processed using that specification. Any fields designated for tracking in the output document specification are ignored. If an IBizTalkChannel object that specifies tracking fields is used with an input document specification containing fields designated for tracking, only the fields specified by the channel are used for tracking.

By logging important data from the input documents that are processed, you can track and analyze detailed information about your operation. For example, an invoice-total field can be logged for every invoice that is sent to your trading partners. You can then determine the total dollar amount of invoices sent to all trading partners over time or determine the total dollar amount of invoices to each individual trading partner.

Related Topics

Document Storage

Document Tracking


Envelopes

The IBizTalkEnvelope object consists of two pieces of information:

  • The type of envelope is specified in the Format property. The document Type should match the envelope Format for "flatfile", "custom xml", "x12", "edifact", and "reliable" document types.

  • The actual envelope file used is specified in the Reference property.

Input document envelopes

An envelope is required if the input document Type is "flatfile" because the envelope contains information about how to parse the document into XML and which parser should process the document. Input "flatfile" documents without an envelope are not processed. For all other input document types, an envelope is optional.

Output document envelopes

Envelopes are used to wrap an output document instance that has been transformed into the native format. The envelope used with an output document is specified on the IBizTalkPort object. An envelope is required if the output document Type is "x12" or "edifact". However, the Reference property is ignored for these format types because indicating that a document is X12 or EDIFACT is sufficient to serialize the document. For output documents with a Type of "custom xml", the Reference property is used if specified. If the Reference property is not specified, "custom xml" documents are submitted for processing in the transformed XML format.

Notes

  • Multiple IBizTalkPort objects can refer to an envelope.

  • The envelope Content and NameSpace properties are not valid until you set the Reference property.

  • When creating a new IBizTalkEnvelope object that uses a namespace that is already registered with BizTalk Server, the new document inherits the Reference property of that namespace. The namespace must be unique (case insensitive) for a new Reference to be created.


Certificates

An IBizTalkCertificateInfo object is automatically created when an IBizTalkPort or an IBizTalkChannel object is instantiated with the CreatePort or the CreateChannel method of the IBizTalkConfig object.

For output documents, access the IBizTalkCertificateInfo object by using the EncryptionCertificateInfo property of the IBizTalkPort object. For input documents, access the IBizTalkCertificateInfo object by using the SignatureCertificateInfo, VerifySignatureCertificateInfo, or DecryptionCertificateInfo property of the IBizTalkChannel object. To obtain the set of all existing IBizTalkCertificateInfo objects, use the Certificates property of the IBizTalkConfig object.

Note

  • All certificates are stored in the local computer store. To configure certificates for the S/MIME components, the script or application accessing the object model must be run in the context of a user account in the BizTalk Server Administrators group.


BizTalk Documents

This section provides information about how to submit documents to Microsoft BizTalk Server 2002. For additional information, see the following sections:

  • For help with specific tasks, see Using Documents.

  • For general background information, see Understanding Documents.

  • For information about COM interfaces and enumerations, see the Documents Reference.

  • For examples of code, see BizTalk Messaging Services Code Samples.


Understanding Documents

This section provides detailed conceptual information that is important to understanding how to submit documents to Microsoft® BizTalk™ Server 2002. The following topics are covered in this section:

  • Submitting

  • Routing


Submitting

All documents must be sent to Microsoft BizTalk Server 2002 by using the Submit or SubmitSync method of the IInterchange interface in order to be processed. If an application is based on Microsoft Windows® and is capable of invoking methods on COM objects, it can submit a document directly. The business application calls the Submit or SubmitSync method of the IInterchange interface, passing in the document or the file path of the document as a string supplied as a parameter. This is the simplest approach because no additional configuration is necessary. However, this method requires that the business application be designed to support direct calls to BizTalk Server 2002.

If the application is not capable of invoking methods on COM objects, receive functions can be used to submit documents to BizTalk Server. Receive functions enable applications to post documents or interchanges to specific locations that BizTalk Server 2002 is monitoring. These locations are defined according to the specific receive function. Each receive function uses event-based monitoring to recognize the presence of a document or interchange. After the data is received by the function, it submits the data to BizTalk Server. For example, a File receive function can be configured to submit a document to BizTalk Server when the business application can save a document as a file but cannot submit it directly. For more information about adding and configuring receive functions, see Manage Receive Functions for a Server Group.

The receive functions are configured to continuously monitor a specific directory or queue for a file to appear and then be submitted to BizTalk Server. HTTP and SMTP protocols are configured outside BizTalk Server. You must create script pages for these transport services.

Notes

  • There is a size limit for interchanges and documents that use logging, which, if exceeded, greatly affects the performance of BizTalk Server. For more information about the size limit, see Interchange and document size limit.

  • A script or application that uses the IInterchange interface to submit documents to BizTalk Server can be run in any user account.

  • When processing envelopes that are compliant with BizTalk Framework 2.0, BizTalk Server should be considered the endpoint with regard to the expiration time. When BizTalk Framework 2.0-compliant documents are submitted to BizTalk Server, either from an application or from a trading partner, the following fields are overwritten if present, or created if absent:
    • In the properties subsection:

      <prop:identity>

      <prop:sentAt>

      <expiresAt>

    • In the receipt information subsection:

      <sendTo>

      <address>

      <sendReceiptBy>

For examples of code, see BizTalk Messaging Services Code Samples.

Sending documents to BizTalk Server 2002 asynchronously

Applications that submit documents asynchronously to BizTalk Server call Submit. Receive functions also call Submit. Submit returns after sending the document. No response document is returned, because the protocol does not support it.

Submit accepts only a string buffer or a file path as the document or interchange. BizTalk Server supports Universal Naming Convention (UNC) and local file path formats.

Sending documents to BizTalk Server 2002 synchronously

Applications that submit documents synchronously to BizTalk Server call SubmitSync.

A synchronous interchange bypasses all queues and executes all the components required by the messaging port on the calling thread. For synchronous protocols, an optional response document is returned to the user, if available. This method is valid only for a single channel match. If the parameters set cause multiple channels to match, synchronous submission returns an error indicating that multiple channel matches are not allowed for synchronous submission. This method can be used only for single document interchanges. If the submission contains multiple documents, synchronous submission returns an error indicating that multiple document submissions are not allowed. This method does not support port groups.

SubmitSync accepts only a string buffer or a file path as the document or interchange. BizTalk Server supports UNC and local file path formats.

Error handling with the Submit and SubmitSync methods

When an error occurs when submitting interchanges or documents to BizTalk Server, an event log entry is created and/or an error is returned to the caller, depending on which method is called and the nature of the failure. Documents submitted can end up in the Suspended queue due to a number of possible conditions. The following table describes what happens when one or more of the documents or interchanges submitted are placed in the Suspended queue due to an error during submission.

Method called | Error returned to caller | Event log entry
Submit | Document failure error | For every document that fails in processing
SubmitSync | Document failure error | None

Related Topics

Routing

Submitting a Document

Documents Reference


Routing

To process a document, Microsoft BizTalk Server 2002 must load the rules that govern how the incoming document instance is to be processed. These rules are known as the channel. A specific IBizTalkChannel object is associated with an IBizTalkPort object and connects two organizations.

To find the channel to process the received document, the server must have the source organization, the destination organization, and the document definition. The server can obtain this information by one of the following methods:

  • This information can be found in the content of the document itself from the data contained in the routing fields (self-routing documents).

  • This information can be explicitly declared in the parameter list of the Submit method of the IInterchange interface (call-based routing).

  • This information can be explicitly declared in the properties of a custom receive function. For more information about receive functions, see Understanding Receive Functions and Document Routing.

  • You can choose to specify the channel to use when calling Submit. This causes the server to bypass the channel selection process.

After the server has this information, it searches for the messaging port/channel pair that matches these routing criteria. If more than one channel matches, each of the channels is processed, possibly resulting in multiple output documents.

Call-based routing

In call-based routing, the source organization identifier (SourceID), the destination organization identifier (DestID), and the name of the document definition (DocName) are specified as parameters of Submit. If SourceQualifier and DestQualifier are not specified, they default to OrganizationName and refer to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. If the Openness flag is set to OpenDest, the DestID is used as the destination address. If SourceID, DestID, or DocName is left blank, the missing information must be provided by the routing information contained within the document. If one of these parameters/fields is not in Submit or in the document, the document goes to the Suspended queue.

Note

  • Note that the queue:// prefix must be used with an open messaging port when a message queue is specified as the destination address.

Self-routing documents

Self-routing documents have the source organization identifier (SourceID), the destination organization identifier (DestID), and the name of the document definition (DocName) defined in the routing tags defined by the document specification, which are contained within the <SelectionFields> tag. If SourceQualifier and DestQualifier are not specified, they default to OrganizationName and refer to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. The BizTalk Framework specification also defines the routing tags for BizTalk Framework–compliant messages. These tags are defined as the <to> and <from> tags under the <endpoint> tag, which is contained in the <header> tag under the root <biztalk> tag. The first tag under the <body> tag determines the document type. For more information, see the BizTalk Framework 2.0 Independent Document Messaging Specification. For X12 or EDIFACT routing, the locations of the routing fields are hard-coded and are not specified in a document specification.


Using Documents

This section provides task-specific information about how to submit documents to Microsoft BizTalk Server 2002. It is highly recommended that you review the Understanding Documents topic as well.

The following topics are covered in this section:

  • Submitting a Document

  • Submitting a Document from a Remote Client

  • Reading the Tracking Database

  • Preprocessing Documents in a Receive Function

  • Accessing the Suspended Queue


Submitting a Document

Use the following steps as a guideline when submitting documents to Microsoft BizTalk Server 2002 with the IInterchange interface.

  1. Determine whether the source organization, destination organization, and document definition name are in the parameters of the Submit or the SubmitSync method of the IInterchange interface or are included in the document; it might be a combination of the two.
    • This information can be explicitly declared in the parameter list of Submit or SubmitSync (call-based routing).

      One or more of these parameters can be left blank and the missing information can be provided by the routing information contained within the document.

    • This information can be found in the content of the document itself from the data in the routing fields (self-routing documents).

    • The user can choose to explicitly call out the specific channel to use when calling Submit. This causes the server to bypass channel selection.

    • This information can be explicitly declared in the properties of a custom receive function.
  2. Decide whether to submit asynchronously or synchronously.
    • Call Submit, passing in the document or the file path of the document as a string supplied as a parameter. BizTalk Server supports URL, UNC, and drive: format for the file path.

      Submit accepts only a string variable as the document or interchange.

    • Call SubmitSync, passing in the document or the file path of the document as a string supplied as a parameter.
      • A response document is returned to the user, if available.

      • This method is valid only for a single channel match.

      • This method can be used only for single-document interchanges.
  3. Decide whether to call some of the Suspended queue methods. (This is optional and can be implemented in the same application or in a different application.)
    • Call the CheckSuspendedQueue method of the IInterchange interface.
      • Retrieve items from the Suspended queue.

      • This returns a list of handles that can subsequently be used to call the DeleteFromSuspendedQueue or the GetSuspendedQueueItemDetails method of the IInterchange interface.
    • Call GetSuspendedQueueItemDetails.

      Retrieve the details about a particular item in the Suspended queue.

    • Call DeleteFromSuspendedQueue.

      Remove items from the Suspended queue.


Submitting a Document from a Remote Client

A document can be submitted to Microsoft BizTalk Server 2002 from a remote client running an application that uses the IInterchange interface. To accomplish this, follow these steps:

  1. Using a computer that has Microsoft BizTalk Server 2002 installed, go to the Start menu, point to Programs, point to Administrative Tools, and then click Component Services.

  2. In the tree pane, click Component Services, expand Computers, expand My Computer, expand COM+ Applications, and then click BizTalk Server Interchange Application.

  3. On the Action menu, click Export.

  4. In the Welcome to the COM Application Export Wizard dialog box, enter the name of an export installation package to be created.

  5. In the Export as area, click the Application proxy option and click Next to finish the wizard.

The COM Application Export Wizard creates a Windows Installer Package file with an .msi extension and its associated cabinet file with a .cab extension. Copy these files to the remote client and run the Windows Installer Package file. Now the remote client can run applications that use the IInterchange interface.

Notes

  • The remote client must be running Microsoft Windows 2000.

  • The computer used to create the installation package acts as an "interchange server" for the remote client that is submitting documents. Therefore, all documents submitted on the remote client are routed through that server.

  • You can also create a remote client during the BizTalk Server 2002 installation.


Reading the Tracking Database

The purpose of the tracking interface, IBizTalkTrackData, is to facilitate programmatic access to the tracking information of Microsoft BizTalk Server 2002. This complements the IInterchange interface so that returns from IInterchange calls can be fed to the IBizTalkTrackData methods to access data about the activity of documents submitted to BizTalk Server 2002.

There can be a one-to-one or a one-to-many relationship between input and output documents. In a normal document flow, one document is submitted to the server, is tracked and possibly transformed, and one document results as output from the server. However, the messaging port can be configured so that one document submitted can result in many documents as output to several destinations.

To read and use information from the Tracking database, perform the following steps:

  1. Get the SubmissionHandle return from the Submit method of the IInterchange interface.

  2. Call the GetInterchanges method, using the SubmissionHandle return as the input. This method returns a list of interchanges contained in that submission, including all the data from the Tracking database. Because transport-specific information (delivery times, receipt flags, and so on) appears in the interchange data, you can look here to confirm or check status on delivery, for example.

  3. Call the GetInDocDetails method, using the SubmissionHandle return as the input. This method returns a list of the documents that were included in that submission. You can look here to find information about an input document (whether a document was valid, how many bytes it contained, and so on).

  4. Call the GetOutDocDetails method, using the SubmissionHandle return as the input. This method returns a list of the documents that were generated as a result of the submission. You can look here to find information about an output document (for example, looking for PO #123456 from a submission made earlier today).

Related Topic

Documents Reference


Preprocessing Documents in a Receive Function

Documents can be submitted to Microsoft BizTalk Server 2002 for processing by using a receive function. Using this mechanism, other applications can send their output files to a specified directory or message queue. BizTalk Server continually monitors the specified location at regular intervals and processes the files or messages placed in that location. BizTalk Server provides interfaces that allow you to create custom preprocessing components. These components process the file or message picked up by the receive function prior to submitting the data to BizTalk Server for processing.

A custom preprocessor component is required to implement the category identifier (CATID) CATID_BIZTALK_CUSTOM_PROCESS in the registry. This allows the BizTalk Server Administration user interface, or administration console, to recognize the custom preprocessor and display it in the Preprocessor list, where it can be selected.

For additional information, see IBTSCustomProcess and IBTSCustomProcessContext.

Transaction Support

If a preprocessing component supports transactions, you must explicitly enable transaction support for that component. To enable transactions with custom preprocessor components, add a registry key by following these steps:

  1. Open the registry editor.

  2. Find the custom component in the registry.

  3. Right-click the component.

  4. Click New and then click DWORD Value.

  5. In the Name field, type UseTxForCustPreProcessor.

  6. Double-click the new UseTxForCustPreProcessor key.

    The Edit DWORD Value dialog box appears.

  7. In the Value data field, type 1.

  8. Click OK.

Related Topics

BizTalk Server Administration User Interface

Receive Functions


Accessing the Suspended Queue

The Suspended queue contains work items that have failed processing for a variety of reasons, including parsing errors, serialization errors, failed transmissions, or the inability to find a channel configuration. You can retrieve or delete items from the queue using the interfaces provided.

Note

  • When accessing or deleting items in the Suspended queue, the script or application must be run in the context of a user account in the BizTalk Server Administrators group. The BizTalk Server Administrators group is created when BizTalk Server 2002 is installed. Additional users can be added to this group as necessary.

Retrieving items from the Suspended queue

To retrieve items from the Suspended queue, applications call the CheckSuspendedQueue method of the IInterchange interface.

CheckSuspendedQueue retrieves a list of items in the Suspended queue that meet the search criteria specified by the parameters of the method. This returns a list of handles that can subsequently be used to call the DeleteFromSuspendedQueue or the GetSuspendedQueueItemDetails method of the IInterchange interface.

Getting item details from the Suspended queue

CheckSuspendedQueue returns a list of handles to items in the Suspended queue. To process these items, you must get the item details associated with each item in the Suspended queue by using GetSuspendedQueueItemDetails.

GetSuspendedQueueItemDetails retrieves the details about an item in the Suspended queue. If this method does not return individual details about this item (because the item has been removed between the time CheckSuspendedQueue was called and the call to this method, for example), each parameter that cannot be determined is returned.

Removing items from the Suspended queue

To remove items from the Suspended queue, applications call DeleteFromSuspendedQueue.

DeleteFromSuspendedQueue removes from the Suspended queue a list of items that meet the search criteria specified by the parameters of the method.


BizTalk Custom Components

This section provides information about how to create custom components and extend Microsoft® BizTalk™ Server 2002 to integrate line-of-business applications and to add features such as encryption and decryption or digital signature. With this information, you can do the following:

  • Create application integration components (AICs) that enable your applications to receive business documents by using BizTalk Server 2002.

  • Extend the functionality of BizTalk Server 2002 by developing custom components to perform digital signature, encryption and decryption, parsing, serializing, and transport of documents.

For additional information, see the following sections:

  • For help with specific tasks, see Using Custom Components.

  • For general background information, see Understanding Custom Components.

  • For information about COM interfaces, see Custom Components Reference.

  • For examples of code, see BizTalk Messaging Services Code Samples.


Understanding Custom Components

This section provides detailed conceptual information that is important to understanding how to extend Microsoft® BizTalk™ Server 2002. BizTalk Server 2002 can perform data transformation, digital signature, encryption and decryption, parsing, serializing, and transport of documents. In addition, you can create your own application integration components (AICs) to extend the capabilities of BizTalk Server 2002.

The following topics are covered:

  • Custom Component Types

  • Application Integration Components

  • Parsers

  • Serializers


Custom Component Types

Custom components can be created for application integration (AICs), encryption, encoding, signing, parsing, and serializing. The following interfaces must be implemented for each component type:

Component types | Interfaces to be implemented
Pipeline components:

AIC
Encryption
Encoding
Signing

 IPipelineComponent, IPipelineComponentAdmin
AIC (lightweight) | IBTSAppIntegration
Parsing IBizTalkParserComponent

By default, BizTalk Server registers the following parser components, listed by ProgID:

  • Edifact: BizTalk.ParserEdifact

  • Flat File: BizTalk.ParserFFile

  • X12: BizTalk.ParserX12

  • XML: BizTalk.ParserXML
Serializing IBizTalkSerializerComponent, IPipelineComponentAdmin (optional)

By default, BizTalk Server registers the following serializer components, listed by ProgID:

  • Edifact: BizTalk.SerializerEdifact

  • Flat File: BizTalk. SerializerFFile

  • X12: BizTalk. SerializerX12

  • XML: BizTalk. SerializerXML


Application Integration Components

When creating an application integration component (AIC), you can implement either the pipeline model using the IPipelineComponent interface or the lightweight model using the IBTSAppIntegration interface.

Application integration components are COM objects that the BizTalk Server state engine calls to deliver data to an application. If a messaging port is configured in BizTalk Server 2002 to include the use of an AIC for application integration, this component is automatically instantiated and passed the requisite data. The component then determines how to handle communicating this data back to the application. This can be done using private API calls, invoking other COM objects, using database writes, and so on.

This section contains the following topics:

  • Pipeline Application Integration Components

  • Lightweight Application Integration Components

By default, AICs run in the LocalSystem account. If another security context is required, set it as part of the implementation of the AIC. However, if an AIC is installed as a COM+ application, an administrator can configure security of the AIC by using the Component Services console.

When developing an AIC using Microsoft Visual Basic®, ensure that all Visual Basic components set the Unattended Execution and Retain in Memory project settings.

Related Topic

Registering Custom Components


Pipeline Application Integration Components

One approach for application integration with BizTalk Server 2002 is the creation of a pipeline component. This is the same model used in Microsoft Site Server 3.0 Commerce Edition for application integration with the Commerce Interchange pipeline (CIP) and the Order Processing pipeline (OPP). BizTalk Server 2002 supports this method so that pipeline components written for application integration for CIP and OPP are compatible. This is also a useful technique when the component requires configuration properties.

The primary entry point for a pipeline component is the Execute method of the IPipelineComponent interface. This is the method that BizTalk Server 2002 calls to transfer control and to pass the data to the component. It is in the implementation of this method that the component does its work.

Related Topics

Lightweight Application Integration Components


Lightweight Application Integration Components

BizTalk Server 2002 supports an additional model for application developers who want a lighter-weight model for application integration, one that does not support a design-time user interface or configuration properties. This model requires a single interface that contains a single method as an entry point. The component is implemented, and the document is passed to it through the ProcessMessage method of the IBTSAppIntegration interface.

IBTSAppIntegration is for applications that do not need properties for their component and need only an entry point for receiving a document. This is a simpler approach to application integration than pipeline components. BizTalk Server 2002 queries for this interface first. If it does not find this interface implemented, it queries for the pipeline component interfaces.


Parsers

The parser has two responsibilities:

  • Convert the documents to XML for later processing.

  • Get the parameters necessary to select the channel (these are the source qualifier, source identifier, destination qualifier, destination identifier, and document definition name). These returned fields are combined with the parameters of the Submit method of the IInterchange interface to select the channels necessary to process the documents.

This interface gets information from the component for one interchange. If the incoming data stream represents multiple interchanges, the server selects the component at every interchange boundary. This simplifies construction of a component because it deals with only one interchange at a time. There is one component instance per thread. No single object needs to be safe for multiple threads. This interface is supported only in C++.

If the ProbeInterchangeFormat method of the IBizTalkParserComponent interface returns an error in the middle of the document list, it blocks the server from detecting more document types, even if they could be handled by a custom parser that follows the failed parser, if there are two or more custom parsers on a server. If the first custom parser fails, any document that follows is not parsed, even if the other custom parser could handle it, because the server ends the entire parsing operation at the time of the failure.

Related Topics

Registering Custom Components

Working with Parsers


Serializers

The serializer converts the document from XML back to its native format. This interface is intended to work on a single interchange and is designed to get information from the component for one interchange. This simplifies the construction of this component because it has to deal with only one interchange at a time. There is only one instance per thread. No single object needs to be safe for multiple threads. The IBizTalkSerializerComponent interface is supported only in C++.

Related Topics

Registering Custom Components

Working with Serializers


Using Custom Components

This section provides task-specific information about how to create server components. It is highly recommended that you review the Understanding Custom Components topic as well.

The following topics are covered:

  • Creating Pipeline Components

  • Creating Receipt Correlator Components

  • Working with Parsers

  • Working with Serializers

  • Registering Custom Components

  • Handling Data Passed to AICs

  • Supporting the Tracking Database with Parser and Serializer Components


Creating Pipeline Components

Use the following steps to create a pipeline component:

  1. Create an Active Template Library (ATL) wizard–generated Inproc server project.

  2. Add a simple COM object.

  3. Go to the Projectname.idl file and remove the dual or custom interface generated by the wizard in step 2.

  4. Verify that the resulting IDL file looks like the code examples that follow. You might choose to implement your own set of interfaces from the ones defined in Pipecomp.idl.

// SimplePipeComponent.idl : IDL source for SimplePipeComponent.dll

//

import "oaidl.idl";

import "ocidl.idl";

import "pipecomp.idl";

[

uuid(D26A52F6-63A0-42B1-8C88-3C71C66BB189),

version(1.0),

helpstring("SimplePipeComponent 1.0 Type Library")

]

library SIMPLEPIPECOMPONENTLib

{

importlib("stdole32.tlb");

importlib("stdole2.tlb");

[

uuid(E66CAF06-18D8-4C70-9D39-5ED9756C21AD),

helpstring("MySimplePipelineComponent Class")

]

coclass MySimplePipelineComponent

{

[default] interface IPipelineComponentAdmin;

interface IPipelineComponent;

interface IPipelineComponentDescription;

};

};

  5. One of the implementations of MySimplePipelineComponent [coclass] is defined in the header file as follows:

// MySimplePipelineComponent.h : Declaration of the

// CMySimplePipelineComponent

#ifndef __MYSIMPLEPIPELINECOMPONENT_H_

#define __MYSIMPLEPIPELINECOMPONENT_H_

#include "resource.h" // main symbols

/////////////////////////////////////////////////////////////////////////////

// CMySimplePipelineComponent

class ATL_NO_VTABLE CMySimplePipelineComponent :

public CComObjectRootEx<CComSingleThreadModel>,

public CComCoClass<CMySimplePipelineComponent, &CLSID_MySimplePipelineComponent>,

public ISupportErrorInfo,

public IDispatchImpl<IPipelineComponentAdmin, &IID_IPipelineComponentAdmin, &LIBID_SIMPLEPIPECOMPONENTLib>,

public IDispatchImpl<IPipelineComponent, &IID_IPipelineComponent, &LIBID_SIMPLEPIPECOMPONENTLib>,

public IDispatchImpl<IPipelineComponentDescription, &IID_IPipelineComponentDescription, &LIBID_SIMPLEPIPECOMPONENTLib>

{

public:

CMySimplePipelineComponent()

{

}

DECLARE_REGISTRY_RESOURCEID(IDR_MYSIMPLEPIPELINECOMPONENT)

DECLARE_PROTECT_FINAL_CONSTRUCT()

BEGIN_COM_MAP(CMySimplePipelineComponent)

COM_INTERFACE_ENTRY2(IDispatch,IPipelineComponentAdmin)

COM_INTERFACE_ENTRY(IPipelineComponentAdmin)

COM_INTERFACE_ENTRY(IPipelineComponent)

COM_INTERFACE_ENTRY(IPipelineComponentDescription)

COM_INTERFACE_ENTRY(ISupportErrorInfo)

END_COM_MAP()

// ISupportsErrorInfo

STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid);

public://IPipelineComponentAdmin

STDMETHODIMP GetConfigData(IDispatch** ppDict );

STDMETHODIMP SetConfigData(IDispatch* pDict );

public://IPipelineComponent

STDMETHODIMP Execute(IDispatch* pdispObject,IDispatch* pdispContext,LONG lFlags,LONG* plErrorLevel);

STDMETHODIMP EnableDesign(BOOL fEnable);

public: //IPipelineComponentDescription

STDMETHODIMP ValuesRead(VARIANT* pvar);

STDMETHODIMP ValuesWritten(VARIANT* pvar);

STDMETHODIMP ContextValuesRead(VARIANT* pvar);

};

#endif //__MYSIMPLEPIPELINECOMPONENT_H_

Related Topics

Application Integration Components

IPipelineComponent

IPipelineComponentAdmin


Creating Receipt Correlator Components

Receipt correlator components can be implemented to correlate documents, groups of documents, and interchanges with their receipts. To use a receipt correlator, you must implement a custom parser by using the IBizTalkParserComponent interface. This is required because the server can obtain only the progID of the receipt correlator to be used by calling the GetNextDocument method on the IBizTalkParserComponent interface.

In addition, with BizTalk Server on the receiver side where the receipt is being generated, the parser component is responsible for putting the acknowledgment status, as well as sufficient information, on the receipt (a Canonical Receipt to begin with, but it can be mapped into other receipt document schemas, such as AK997 in EDI) to allow the correlator component on the sender side to uniquely identify the original outbound interchange, group, or document record. For an XML document, using the GUID is usually sufficient. But for EDI interchanges, because GUID cannot be used (there is no placeholder for any GUID in an EDI interchange), a combination of EDI-specific fields is needed for this unique identifier. For instance, the default X12 correlator component uses a combination of the following fields for this purpose: version, release, functional group ID, control ID, source application name, and destination application name.

Whenever the server receives a receipt as an inbound document, the parser component's responsibility is to detect the inbound document as being a receipt, to extract all relevant information needed for correlation, and to place the receipt onto the transport dictionary. Upon returning from the GetNextDocument method call, the parser should set the DocIsReceipt parameter to TRUE and the CorrelationCompProgID parameter to the progID of the corresponding correlator component.

The server calls the Correlate method on the IBizTalkCorrelation interface, and passes in a pointer to the IBizTalkAcknowledge object and the transport dictionary containing the receipt as the working data. Then the receipt correlator's implementation of the Correlate method extracts all relevant information about the document, document group, or interchange that should have been set by the parser component from the transport dictionary. Using this information, the Correlate method then calls AckDocument, AckGroup, or AckInterchange on the IBizTalkAcknowledge interface and sets the DTA_ACK_STATUS value for that document, group, or interchange.

Note that the server does not immediately call IBizTalkCorrelation. The receipt document and the correlation progID are stored to the database for later correlation. When the document is picked up for processing, the correlation component is created and invoked with the transport dictionary that was given by the parser component and a pointer to IBizTalkAcknowledge.

Related Topics

Submitting Documents with Receipts

Understanding Receipts


Working with Parsers

The following tables show the possible sequence of calling the methods of the IBizTalkParserComponent interface, based on the following sample interchanges.

If you have an interchange with two groups, with two documents in the first group and one in the second, the methods are called in the following sequence:

Method | Return
ProbeInterchangeFormat | Non-empty format string
GetInterchangeDetails | N/A
GroupsExist | True
GetGroupDetails | N/A
GetNextDocument | The LastDoc parameter is set to False.
GetNativeDocumentOffsets | N/A
GetNextDocument | The LastDoc parameter is set to True.
GetNativeDocumentOffsets | N/A
GetGroupSize | The LastGroup parameter is set to False.
GetGroupDetails | N/A
GetNextDocument | The LastDoc parameter is set to True.
GetNativeDocumentOffsets | N/A
GetGroupSize | The LastGroup parameter is set to True.

If you have an interchange with two documents, the methods are called in the following sequence:

Method | Return
ProbeInterchangeFormat | Non-empty format string
GetInterchangeDetails | N/A
GroupsExist | False
GetNextDocument | The LastDoc parameter is set to False.
GetNativeDocumentOffsets | N/A
GetNextDocument | The LastDoc parameter is set to True.
GetNativeDocumentOffsets | N/A

Related Topics

Parsers

IBizTalkParserComponent

Supporting the Tracking Database with Parser and Serializer Components


Working with Serializers

To create a custom serializer component, you need to perform the following tasks:

  • Create a COM component that implements the IBizTalkSerializerComponent and IPipelineComponentAdmin interfaces.

  • Register this component and include the category identifiers CATID_BIZTALK_COMPONENT and CATID_BIZTALK_SERIALIZER in the registry. For more information, see Registering Custom Components.

  • Create Active Server Pages (ASP) files for setting custom property values on your serializer component by using the pre-defined user interface management functions. These functions are available in the ASP include files located in the folder \Microsoft BizTalk Server\Messaging Manager\pipeline on the BizTalk Server installation drive. For more information about the ASP file format, see "ASP file formats" that follows.

  • Place the ASP files in the pipeline folder and name the files using these formats:
    File name | Description
    BizTalk_ComponentName_1.asp | Displays a dialog box that reads the serializer key values from the IDictionary object. These values are displayed to the user for modification.
    BizTalk_ComponentName_1_post.asp | Updates the serializer dictionary with the new key values set by the user.

  • Use the SetConfigComponent method to associate the custom serializer component with a channel.

After these tasks are completed, the user can access these settings by clicking Advanced on the Channel Properties page in BizTalk Messaging Manager. For more information, see Set advanced configuration properties.

ASP file formats

When using the functions provided in the ASP include files located in the folder \Microsoft BizTalk Server\Messaging Manager\pipeline on the BizTalk Server installation drive, use the following general format:

<!--#INCLUDE FILE="pe_edit_header.asp" -->

<-- optional HTML formatting tags here -->

<%

optional calls to input functions here

%>

<!--#INCLUDE FILE="pe_edit_footer.asp" -->

The following functions can be used in the ASP pages for displaying text or retrieving specific types of information from the user. These functions are defined in the file pe_global_edit.asp:

  • DisplayReadonlyText

  • GetLabelAccel

  • InputArrayAccel

  • InputCheckBoxAccel

  • InputFloatAccel

  • InputNumberAccel

  • InputPasswordAccel

  • InputRadioAccel

  • InputSimpleListAccel

  • InputTextAccel

Method Sequences

The following tables show the possible sequence of calling the methods of the IBizTalkSerializerComponent interface, based on the following sample interchanges.

If you have an interchange with one document, the methods are called in the following sequence:

Method | Return
Init | The numdocs parameter is set to 1.
AddDocument | The docHandle parameter is set to 0.
GetInterchangeInfo | The numGroups parameter is set to 0.
GetDocInfo | The docHandle parameter is set to 0.

If you have an interchange with one group, with one document in the group, the methods are called in the following sequence:

Method | Return
Init | The numdocs parameter is set to 1.
AddDocument | The docHandle parameter is set to 0.
GetInterchangeInfo | The numGroups parameter is set to 1.
GetGroupInfo | The numdocs parameter is set to 1.
GetDocInfo | The docHandle parameter is set to 0.

If you have an interchange with two groups, with two documents in the first group and one in the second, the methods are called in the following sequence (this assumes support of batching):

Method | Return
Init | The numdocs parameter is set to 3.
AddDocument | The handle parameter is set to 0.
AddDocument | The handle parameter is set to 1.
AddDocument | The handle parameter is set to 2.
GetInterchangeInfo | The numGroups parameter is set to 2.
GetGroupInfo | The numdocs parameter is set to 2.
GetDocInfo | The handle parameter is set to 1.
GetDocInfo | The handle parameter is set to 0.
GetGroupInfo | The numdocs parameter is set to 1.
GetDocInfo | The handle parameter is set to 2.

Related Topics

Serializers

Supporting the Tracking Database with Parser and Serializer Components


Registering Custom Components

To use a custom component in BizTalk Server 2002, the component must be registered with the category IDs for all pipeline components and for the specific type of pipeline component.

Register the component as an out-of-process component to provide better isolation. A component can be registered as an in process (inproc) component to increase its performance. However, an inproc component that fails to respond during an error condition might cause BizTalk Server to fail. Therefore, a component should be thoroughly tested before registering it as an inproc component.

Note

  • An out-of-process component registered as a COM+ application must be configured to run in an identity other than the interactive user. For more information about Component Services and COM+, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and browse to Component Services in the Platform SDK.

BizTalk Server category identifiers

Custom components that are used in BizTalk Server must be associated with one or more category identifiers (CATID). The following table shows the category identifiers defined by BizTalk Server.

CATID | GUID | Description
CATID_BIZTALK_ AIC | BD193E1D-D7DC-4B7C-B9D2-92AE0344C836 | Identifies the component as an application integration component (AIC).
CATID_BIZTALK_ COMPONENT | 5C6C30E7-C66D-40E3-889D-08C5C3099E52 | Identifies the component as a BizTalk Server component. All components that are used with BizTalk Server must implement this category identifier.
CATID_BIZTALK_ CUSTOM_PROCESS | 20E8080F-F624-4401-A203-9D99CF18A6D9 | Identifies the component as a custom preprocessor for a receive function.
CATID_BIZTALK_ IDocSpecExtension | 711E279C-DE24-11D2-974B-00C04F680FE7 | Identifies the component as an extension module for importing XML documents.
CATID_BIZTALK_ MapEditFunctoids | 2560F3BF-DB47-11D2-B3AE-00C04F72D6C1 | Identifies the component as a custom functoid that is displayed in the functoid palette.
CATID_BIZTALK_ PARSER | C0DCDF4E-692C-11D2-89E7-00C04F79DBAA | Identifies the component as a parser that is used to process inbound documents.
CATID_BIZTALK_ SERIALIZER | AFCC065F-E0A6-47A6-B0A8-ECAA2FEEE2F4 | Identifies the component as a serializer that is used to process outbound documents.

Assigning affinity

Each component must be associated with two category IDs. One category ID marks the component as a BizTalk Server component. A component so marked appears in a list of components in the BizTalk Server administration console. The second category ID indicates the type or purpose of the component. This second association is called affinity, which allows BizTalk Server to determine the context in which the component can be used. For example, only those components whose affinity is registered as an application integration component (AIC) appear in the list of available components when an AIC transport type has been selected in BizTalk Messaging Manager.

To register affinity for an AIC created with Microsoft Visual C++® using ATL, include the following code in your header file:

#include "bts_sdk_guids.h"

// Implement the Component and AIC Category IDs (CATID)

BEGIN_CATEGORY_MAP(AIC_ClassName)

IMPLEMENTED_CATEGORY(CATID_BIZTALK_COMPONENT)

IMPLEMENTED_CATEGORY(CATID_BIZTALK_AIC)

END_CATEGORY_MAP()

To register affinity for an AIC created with Microsoft Visual Basic:

  1. After registering your component using Regsvr32.exe, search the registry for the CLSID of your AIC under the following key:

    HKEY_CLASSES_ROOT\CLSID

  2. Expand the Implemented Categories key of your AIC.

  3. Add two new keys with the following names:

    HKEY_CLASSES_ROOT\CLSID\AIC_CLSID\Implemented Categories\{5C6C30E7-C66D-40e3-889D-08C5C3099E52}

    HKEY_CLASSES_ROOT\CLSID\AIC_CLSID\Implemented Categories\{BD193E1D-D7DC-4b7c-B9D2-92AE0344C836}

These GUIDs can be found in bts_sdk_guids.h in the Program Files\Microsoft BizTalk Server\SDK\Include folder. The first key shown in step 3 above identifies the AIC as a BizTalk Server component (CATID_BIZTALK_COMPONENT). The second key shown in step 3 above identifies the component as an AIC (CATID_BIZTALK_AIC).

Testing affinity

To test affinity, use BizTalk Messaging Manager to create a port that uses the AIC. For more information, see Select an application integration component.

Related Topics

IFunctoid Interface

ISchemaImporter Interface

IBTSCustomProcess

Parsers

Serializers


Handling Data Passed to AICs

The proper method for handling data returned by an application integration component (AIC) depends on several factors, including programming language, the characteristics of the channel being used, and the document being passed.

For an AIC written in Visual Basic, you receive a buffer that contains Unicode characters, ANSI characters, or bytes.

The Direct Integration sample contains an ATL component that unpacks binary buffers returned as BSTR data. The component defines and implements the IConvertBstr interface, which defines a single method called Convert:

HRESULT Convert([in] BSTR bstrData, [out,retval] VARIANT* psaData);

When a buffer is passed as a BSTR to this method, the component creates a safe array of characters. The size of the array is the size of the buffer passed in the BSTR. A simple operation of memory copying helps translate the BSTR data to a safe array. Convert can be used by an AIC to convert the data to a format that can be iterated, as shown in the following code:

STDMETHODIMP CConvertBstr::Convert(BSTR bstrData, VARIANT *psaData) {

HRESULT hr = S_OK;

SAFEARRAY *psa = NULL;

BYTE HUGEP*psaBuffer = NULL;

SAFEARRAYBOUND rgsaBound[1];

UINT nDataLength = 0;

Determine if the arguments passed to Convert are valid, as shown in the following code:

if (!psaData || !bstrData)

return E_FAIL;

Clear the variant data type, as shown in the following code:

hr = VariantClear(psaData);

if (FAILED(hr))

return hr;

The client code must initialize the variant. Then, retrieve the length of the allocated BSTR, in bytes, as shown in the following code:

nDataLength = SysStringByteLen(bstrData);

At this point, construct a SAFEARRAY that will contain the bytes from the input BSTR data type, as shown in the following code:

rgsaBound[0].lLbound = 0;

rgsaBound[0].cElements = (ULONG)nDataLength;

psa = SafeArrayCreate(VT_UI1, 1, rgsaBound) ;

if (!psa)

return E_FAIL;

SafeArrayAccessData(psa, (void HUGEP**) &psaBuffer);

memcpy(psaBuffer, bstrData, nDataLength);

SafeArrayUnaccessData(psa);

Finally, return the SAFEARRAY through the output parameter, as shown in the following code:

V_VT(psaData) = VT_ARRAY | VT_UI1;

V_ARRAY(psaData) = psa;

return hr;

}

In addition, all pipeline AICs receive an IDictionary object, containing a set of fields. Every IDictionary object contains a working_data field. Several other fields could be present, including the following string values supplied by the server for all AICs:

  • Src_ID_Type: The type of identifier used for the source organization.

  • Src_ID_Value: The value of the source organization identifier.

  • Dest_ID_Type: The type of identifier used for the destination organization.

  • Dest_ID_Value: The value of the destination organization identifier.

  • Document_Name: The name of the input document definition.

  • Tracking_ID: A key value that is based on the globally unique identifier (GUID) and used for tracking.

  • Src_Filename: The name of the source document.

  • Src_Filepath: The file path of the source document.

  • Out_Codepage: The codepage used by the component to interpret the BSTR data.

Related Topics

Supporting the Tracking Database with Parser and Serializer Components

Execute Method


Supporting the Tracking Database with Parser and Serializer Components

When creating a custom parser or serializer, you might want your component to support the BizTalk Server Tracking database. To accomplish this, the component must use the IDictionary interface to add key/value pairs into the database.

Interchange table

The following table contains the list of keys that can be used to support the Tracking database from the interchange level with a custom component. The table used in the database is dta_interchange_details.

Dictionary key | Inbound or outbound | Column logged in Tracking database | Description
Src_ID_Type | Both | *nvcSrcAliasQualifier | This is the qualifier for the source organization. This value can come from a parameter supplied in a Submit call or from a receive function in the BizTalk Server Administration user interface. A parser can overwrite this value to manipulate the routing information used for channel selection.
Src_ID_Value | Both | *nvcSrcAliasId | This contains the value of the qualifier of the source organization. This value can come from a parameter supplied in a Submit call or from a receive function in the BizTalk Server Administration user interface. A parser can overwrite this value to manipulate the routing information used for channel selection.
In_Src_ID_App | Inbound | nvcSrcAppName | This is the interchange level identifier for the source application of an EDI interchange. When the parser sets the value with this dictionary key, the value is logged on the inbound interchange in the Tracking database.
Dest_ID_Type | Both | *nvcDestAliasQualifier | This is the qualifier for the destination organization. This value can come from a parameter supplied in a Submit call or from a receive function in the BizTalk Server Administration user interface. A parser can overwrite this value to manipulate the routing information used for channel selection.
Dest_ID_Value | Both | *nvcDestAliasId | This contains the value of the qualifier of the destination organization. This value can come from a parameter supplied in a Submit call or from a receive function in the BizTalk Server Administration user interface. A parser can overwrite this value to manipulate the routing information used for channel selection.
In_Dest_ID_App | Inbound | nvcDestAppName | This is the interchange level identifier for the destination application of an EDI interchange. When the parser sets the value with this dictionary key, the value is logged on the inbound interchange in the Tracking database.
interchange_id | Inbound | nvcControlID | This is the unique control number used to identify an EDI interchange instance between trading partners. When the parser sets the value with this dictionary key, the value is logged on the inbound interchange in the Tracking database.
interchange_version | Inbound | nvcVersion | This is the version of an EDI interchange. When the parser sets the value with this dictionary key, the value is logged on the inbound interchange in the Tracking database.
Out_Src_ID_App | Outbound | *nvcSrcAppName | This is the interchange level identifier for the source application of an EDI interchange. When the serializer sets the value with this dictionary key, the value is logged on the outbound interchange in the Tracking database.
Out_Dest_ID_App | Outbound | *nvcDestAppName | This is the interchange level identifier for the destination application of an EDI interchange. When the serializer sets the value with this dictionary key, the value is logged on the outbound interchange in the Tracking database.
out_interchange_id | Outbound | *nvcControlID | This is the unique control number used to identify an EDI interchange instance between trading partners. The serializer usually generates this unique value. When the serializer sets the value with this dictionary key, the value is logged on the outbound interchange in the Tracking database.
out_interchange_version | Outbound | *nvcVersion | This is the version of the EDI standard. When the serializer sets the value with this dictionary key, the value is logged on the outbound interchange in the Tracking database.

Note

  • The columns of the dta_interchange_details table marked with an asterisk (*) are used for receipt correlation.

Group table

The following table contains the list of keys that can be used to support the Tracking database from the group level with a custom component. The table used in the database is dta_group_details. This table applies to both inbound and outbound documents.

Dictionary key | Column logged in Tracking database | Description
group_id | *nvcControlID | This is the unique control number of a group instance within an EDI interchange. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database. For outbound document processing, the serializer usually generates this value.
functional_identifier | *nvcFunctionalGroupID | This is the code for the type of documents in an EDI group. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database. In the serializer, this value can be read from the document's PropertySet.
application_sender_code | *nvcSrcAppName | This is the group level identifier for the source application in an EDI group. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database. In the serializer, this value can be read from the document's PropertySet.
application_receiver_code | *nvcDestAppName | This is the group level identifier for the destination application in an EDI group. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database. In the serializer, this value can be read from the document's PropertySet.
standards_version | *nvcVersion | This is the version of the EDI standard. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database.
standards_release | *nvcRelease | This is the release of the version of the EDI standard. Both the parser and the serializer can set the value with this key. The value is logged on the inbound and the outbound group, respectively, in the Tracking database.

Note

The columns of the dta_group_details table marked with an asterisk (*) are used for receipt correlation.

Inbound document table

The following table contains the list of keys that can be used to support the Tracking database from the document level with a custom component. The table used in the database is dta_indoc_details. This table applies to inbound documents only.

Dictionary key | Column logged in Tracking database | Description
doc_id | nvcControlID | This is the unique control number of an EDI document instance. When the parser sets the value with this dictionary key, the value is logged on the inbound document in the Tracking database.
standards_version | nvcVersion | This is the version of the EDI standard. When the parser sets the value with this dictionary key, the value is logged on the inbound document in the Tracking database.
standards_release | nvcRelease | This is the release of the version of the EDI standard. When the parser sets the value with this dictionary key, the value is logged on the inbound document in the Tracking database.
doc_type | nvcDocType | This is the document type or transaction set identifier. When the parser sets the value with this dictionary key, the value is logged on the inbound document in the Tracking database.

Outbound document table

The following table contains the list of keys that can be used to support the Tracking database from the document level with a custom component. The table used in the database is dta_outdoc_details. This table applies to outbound documents only.

Dictionary key | Column logged in Tracking database | Description
out_doc_doc_id | nvcControlID | This is the unique control number of an EDI document instance. When the serializer sets the value with this dictionary key, the value is logged on the outbound document in the Tracking database.
out_doc_syntax | nvcSyntax | This is the code for document syntax, such as XML, X12, EDIFACT, H7, and so on. When the serializer sets the value with this dictionary key, the value is logged on the outbound document in the Tracking database.
out_doc_standards_version | nvcVersion | This is the version of the EDI standard. When the serializer sets the value with this dictionary key, the value is logged on the outbound document in the Tracking database. In the serializer, this value can be read from the document's PropertySet.
out_doc_standards_release | nvcRelease | This is the release of the version of the EDI standard. When the serializer sets the value with this dictionary key, the value is logged on the outbound document in the Tracking database. In the serializer, this value can be read from the document's PropertySet.
out_doc_doc_type | nvcDocType | This is the document type or transaction set identifier. When the serializer sets the value with this dictionary key, the value is logged on the outbound document in the Tracking database.
Tracking_ID | uidTrackingGUID | This is the tracking identifier of the document for which a receipt is generated.

Note

  • The Tracking_ID key is used when calling the AckDocument method.

Interchange and document tables

The following table contains the list of keys that can be used to support the Tracking database from the interchange and document level with a custom component. The table used in the database for interchange data is dta_interchange_data. The table used in the database for document data is dta_document_data.

Dictionary key | Inbound or outbound | Column logged in Tracking database | Description
in_codepage | Inbound | nCodePage | This is the system code page value with which interchange/document data is encoded. When the parser sets the value with this dictionary key, the value is logged in the data record related to the inbound interchange/document in the Tracking database.
out_codepage | Outbound | nCodePage | This is the system code page value with which interchange/document data is encoded. When the serializer sets the value with this dictionary key, the value is logged in the data record related to the outbound interchange/document in the Tracking database.

Related Topic

Understanding the Tracking Database Schema


BizTalk Orchestration Services

The interfaces in this section provide access to XLANG Scheduler System Managers, XLANG group managers, XLANG schedule instances, and XLANG ports.

The XLANG Scheduler System Manager provides moniker resolution and maintains a collection of group managers. A group manager runs in every COM+ application that has been designated as an XLANG schedule host, and maintains a collection of XLANG schedule instances. An XLANG schedule instance represents a running XLANG schedule that can be queried for information, such as the schedule's completion status. For XLANG schedules with a COM-bound port, a proxy object can be used to obtain a reference to the interface specified in the port binding.

  • For help with specific tasks, see Using Orchestration Services.

  • For general background information, see Understanding Orchestration Services.

  • For information about COM interfaces and error messages, see the Orchestration Services Reference.

Related Topic

Moniker Syntax


Understanding Orchestration Services

This section provides detailed conceptual information that is important to understanding how to access and work with BizTalk Orchestration Services. The following topics are covered in this section:

  • XLANG Interfaces

  • XLANG Schedule Correlation

The interfaces described in this section provide access to XLANG Scheduler System Managers, XLANG group managers, XLANG schedule instances, and XLANG ports.


XLANG Interfaces

The XLANG Scheduler System Manager provides moniker resolution and maintains a collection of group managers. A group manager runs in every COM+ application that has been designated as an XLANG schedule host, and maintains a collection of XLANG schedule instances. An XLANG schedule instance represents a running XLANG schedule that can be queried for information, such as the schedule's completion status. For XLANG schedules with a COM-bound port, a proxy object can be used to obtain a reference to the interface specified in the port binding.

The following illustration shows the relationship between the XLANG interfaces covered in this section, and the corresponding monikers.

XLANG Scheduler interfaces

The following XLANG schedule interfaces are available:

Administrator interfaces:

  • IWFGroupAdmin

  • IWFSystemAdmin

Schedule instance interfaces:

  • IWFProxy

  • IWFWorkflowInstance


XLANG Schedule Correlation

XLANG schedule correlation enables you to use a single message queue shared across multiple XLANG schedule instances, allowing incoming messages on that queue to be correlated to the correct running XLANG schedule instance. Src_XLANG_InstanceID and Dest_XLANG_InstanceID are dictionary keys created to take advantage of XLANG schedule correlation. The XLANG Scheduler Engine supports the ability to set the globally unique identifier (GUID) assigned to the schedule instance, or InstanceID, as the message label on received Message Queuing messages. These keys are provided by BizTalk Messaging Services to supply a simple mechanism to save and retrieve the data from the XLANG Scheduler Engine. By using these keys, you do not need to write code to retrieve and look up the InstanceIDs in the XLANG schedule, and you can leverage the existing BizTalk Messaging transports.

The Src_XLANG_InstanceID dictionary key appears on messages that originate from the BizTalk Messaging binding in an XLANG schedule instance, as long as the message is declared to send the InstanceID. This information can be used by a component in the messaging port to store the InstanceID to a custom database with a business-level correlation ID.

When a response message is received for a business interaction, the messaging port bound to the running XLANG schedule instance must contain the InstanceID in order to send the data to the correct running XLANG schedule instance. To do this, the Dest_XLANG_InstanceID key is extracted by BizTalk Messaging Services and placed on the Message Queuing label for the receiving queue. The key is set by custom pipeline components that look up the XLANG schedule InstanceID based on the business-level correlation ID.

Note

  • The tracking dictionary does not use these keys and they are not defined in a database table. To capture the correlation state, you need to implement a custom database.

For more information, run the E-Procurement Sample, which demonstrates the XLANG schedule correlation feature.

Related Topic

Instance Management


Using Orchestration Services

This section provides task-specific information about how to use BizTalk Orchestration Services. It is highly recommended that you review the Understanding Orchestration Services topic as well.

The following topics are covered in this section:

  • Activating an XLANG Schedule Instance

  • Accessing a Running XLANG Schedule Instance

  • Accessing the XLANG Scheduler System Manager

  • Accessing Group Managers


Activating an XLANG Schedule Instance

Use IWFProxy to obtain a schedule instance. If IWFProxy is used on a non-COM port binding, an error is returned.

A reference to IWFProxy can be obtained from:

  • The Port property available on the IWFWorkflowInstance interface.

  • An XLANG schedule moniker that specifies the port name.

The following Microsoft Visual Basic code sample shows how to activate an XLANG schedule on the local computer by using a moniker, and obtain a reference to the named port on that XLANG schedule instance.

Dim oPort As Object

Set oPort = GetObject("sked:///C:\schedules\test.skx/PortA")

At this point, the oPort variable contains a reference to the COM object bound in PortA of the schedule instance.

For additional information about monikers, see Moniker Syntax.

Note

  • When using C++, the COM CoGetObject function is used in place of GetObject.


Accessing a Running XLANG Schedule Instance

Use IWFWorkflowInstance to gather information about a specific running schedule instance.

A reference to IWFWorkflowInstance can be obtained from:

  • The WorkflowInstance property available on the IWFProxy interface.

  • The collection of IWFWorkflowInstance objects returned by the IWFGroupAdmin object.

  • An XLANG schedule moniker.

The following Microsoft Visual Basic code sample shows how to instantiate an XLANG schedule on the local computer and obtain a reference to that schedule instance.

Dim oWFI As IWFWorkflowInstance

Set oWFI = GetObject("sked:///C:\schedules\test.skx")

To obtain a reference to all currently running schedule instances in a group manager, you can access the collection of IWFWorkflowInstance objects contained by the IWFGroupAdmin object. The following Microsoft Visual Basic code displays the fully qualified name of each schedule instance running in the default XLANG Scheduler Group Manager.

Dim oGM As IWFGroupAdmin

Dim oWFI As IWFWorkflowInstance

Set oGM = GetObject("sked://!XLANG Scheduler")

For Each oWFI In oGM

MsgBox ("XLANG Schedule: " + oWFI.FullyQualifiedName)

Next

When using multiple group managers, you can determine the group manager associated with any schedule instance by following these steps:

  1. Retrieve the FullyQualifiedName property of the IWFWorkflowInstance object.

  2. Parse the group manager name out of the moniker string returned.

    This is the portion that begins with an exclamation point (!) and ends with a slash (/).

  3. Obtain a reference to the IWFGroupAdmin object using a moniker created with the group manager name from step 2.

For additional information about monikers, see Moniker Syntax.

Notes

  • When using C++, the COM CoGetObject function is used in place of GetObject.

  • When accessing this object in Microsoft Visual Basic, you must declare your object variable with the appropriate type information rather than using the Object type. For example:

Dim myInstance As IWFWorkflowInstance


Accessing the XLANG Scheduler System Manager

Use IWFSystemAdmin to start, stop, and retrieve information about the group managers.

To obtain a reference to this object, you can invoke the COM GetObject function using a moniker. The following Microsoft Visual Basic code sample shows how to obtain a reference to the XLANG Scheduler System Manager on the local computer.

Dim oSM As SysMgr

Set oSM = GetObject("sked://")

This object also enumerates a collection of the IWFGroupAdmin objects that represent the group managers associated with this XLANG Scheduler System Manager.

For additional information about monikers, see Moniker Syntax.

Note

  • When using C++, the COM CoGetObject function is used in place of GetObject.


Accessing Group Managers

To obtain a reference to an IWFGroupAdmin object, you can invoke the COM GetObject function using a moniker. The following Microsoft Visual Basic code sample shows how to obtain a reference to the default XLANG Scheduler Group Manager on the local computer.

Dim oGM As IWFGroupAdmin

Set oGM = GetObject("sked://!XLANG Scheduler")

To obtain a reference to other group managers, replace "XLANG Scheduler" with the name of the COM+ application that has been designated as an XLANG Scheduler Engine host or group manager. You can determine whether a COM+ application is a group manager by using the IsWorkflowHost method on IWFSystemAdmin.

You can also obtain a reference to all group managers associated with the XLANG Scheduler System Manager through the collection of IWFGroupAdmin objects contained by the SysMgr object. The following Microsoft Visual Basic code displays the fully qualified name of each group manager.

Dim oSM As SysMgr

Dim oGM As IWFGroupAdmin

Set oSM = GetObject("sked://")

For Each oGM In oSM

MsgBox ("Group Manager: " + oGM.FullyQualifiedName)

Next

The IWFGroupAdmin object also enumerates a collection of the IWFWorkflowInstance objects that represent currently running schedule instances for this group manager.

You can determine the XLANG Scheduler System Manager associated with any group manager by following these steps:

  1. Retrieve the FullyQualifiedName property of the IWFGroupAdmin object.

  2. Parse the XLANG Scheduler System Manager name out of the moniker string returned.

    This is the portion between the sked:// prefix and the exclamation point (!).

  3. Obtain a reference to the IWFSystemAdmin object using a moniker created with the XLANG Scheduler System Manager name from step 2.

For additional information about monikers, see Moniker Syntax.

Note

  • When using C++, the COM CoGetObject function is used in place of GetObject.


BizTalk Managing and Monitoring

Windows Management Instrumentation (WMI) is a data-management layer included in Microsoft® Windows® 2000. Microsoft BizTalk™ Server 2002 uses the WMI layer to encapsulate administrative functions that support the management of systems in an enterprise.

  • For help with specific tasks, see Using Managing and Monitoring.

  • For general background information, see Understanding Managing and Monitoring.

  • For information about COM interfaces, see the Managing and Monitoring Reference.

This section contains sample code in Microsoft Visual Basic® and Visual Basic Script.


Understanding Managing and Monitoring

When you use the BizTalk Server Administration Microsoft Management Console (MMC) snap-in (the administration console) to change group, server, queue, and database management settings, the new values are stored in the BizTalk Messaging Management database through the BizTalk Server WMI provider. In BizTalk Server 2002, this WMI provider uses a Microsoft® SQL Server™ database to store administrative objects. All timestamps are created by using the local time on the computer that is running SQL Server. However, the WMI provider refers to all timestamps in coordinated universal time (UTC). The administration console then converts the timestamps back to local time for display.

The WMI provider acts as an intermediary between WMI and the administration console MMC snap-in. The WMI provider gathers information from a resource (managed object) and makes it available to management applications through the WMI API.

The BizTalk Server schema classes are registered and defined by using Managed Object Format (MOF), which is a compiled language based on the Interface Definition Language (IDL). You place this information in an .mof file that you submit to the MOF compiler, Mofcomp.exe.

This section contains the following topics:

  • BizTalk Server Namespace

  • BizTalk Server Provider and Registration

  • Custom Counters

The MOF code examples in the following topics are taken from the InterchangeProvSchema.mof file found in the \Program Files\Microsoft BizTalk Server\Setup folder. This file, along with SrvEvents.mof, contains the BizTalk Server namespace, provider, provider registration, and schema class definitions.

To access the WMI database layer programmatically, see Managing and Monitoring Reference, which documents the BizTalk Server WMI schema classes that correspond to the Administration objects.


BizTalk Server Namespace

Every WMI namespace contains a set of system classes, including __NAMESPACE. A namespace groups a collection of classes into logical units. Every computer has a defined namespace at the top of the hierarchy called the Root namespace. The location of a namespace is described by a path.

In the following MOF code, "MicrosoftBizTalkServer" is specified as the value for the Name property of the __NAMESPACE system class for BizTalk Server:

#pragma namespace ("\\\\.\\Root")

instance of __Namespace

{

Name = "MicrosoftBizTalkServer";

}

BizTalk Server defines the "MicrosoftBizTalkServer" namespace as a sibling of the Root namespace, logically distinguishing the BizTalk Server–managed environment from other managed environments.


BizTalk Server Provider and Registration

When WMI receives a request from a BizTalk Server management application, it forwards the request to the WMI provider, "InterchangeProv." The WMI provider retrieves, modifies, deletes, and/or enumerates instances of the BizTalk Server schema classes.

"InterchangeProv" is a custom provider designed to interact with the managed objects in the BizTalk Server environment. For a complete reference of these managed objects and their properties and methods, see Managing and Monitoring Reference.

The BizTalk Server instance provider supports data retrieval, data modification, data deletion, data enumeration, and query processing.

For more information about how to author and interpret .mof files, see the article "Managed Object Format (MOF) Language," in the WMI SDK on the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp).

The BizTalk Server WMI classes are defined in text files by using the Managed Object Format (MOF). Note that each class has a key property qualifier. The key property qualifier tells you that any instance of that class (or any instance of a derived class) can be uniquely identified by the value of the key property qualifier. This is a concept borrowed from database technologies.

To access the functionality provided by WMI you call a set of DCOM interfaces, including IWbemClassObject and IWbemServices. These interfaces make it possible to write management applications that work with classes and instances that are managed by WMI.

In addition, you can access WMI from environments that support Automation objects through scripting objects that wrap the DCOM interfaces. For example, the SWbemObject class wraps the IWbemClassObject interface, and SWbemServices wraps IWbemServices. When using WMI with the BizTalk Server schema classes, you can get complete access to WMI through Microsoft Visual Basic or Visual Basic Scripting Edition (VBScript). Visual Basic projects can access these objects by adding Microsoft WMI Scripting V1.1 Library in the Reference dialog box.

The Component Object Model (COM) API is available directly to C/C++ programmers. You can use the Scripting API to develop script and applications based on Microsoft Visual Basic that you can use to view or control managed objects.

For a description of the interfaces in the WMI COM API, see the article "COM API for WMI," in the WMI SDK on the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp).

For a description of the interfaces in the Scripting API, see the article "Scripting API for WMI," in the WMI SDK on the MSDN Online Library Web site.


Custom Counters

Custom counters are WMI class instances based on custom queries of the Tracking database. After they are created, these custom counters can be consumed by user-defined rules in Microsoft Operations Manager 2000 (MOM).

This section contains the following topics:

  • Custom Counter Query Properties

  • Custom Counters Validation

To programmatically create, delete, and update custom counters, see Creating a Custom Counter Using WMI.

For information about using BizTalk Server 2002 together with MOM, see About Microsoft Operations Manager.

The BizTalk Server 2002 Management Pack module includes a sample custom counter performance processing rule called "Sample - Custom Counter." This sample executes the query defined in the WMI custom counter class to acquire the number of documents in the Tracking database.

Notes

  • Unless you want to construct a regular expression when working with custom counters, there are a list of characters that need special consideration:

    [ ], ^, %, _

    You should enclose these characters in [ ] braces. For example, the string "Org%ani^za_tio[n", should be replaced by "Org[%]ani[^]za[_]tio[[]n".

  • Only the following custom counter setting properties can accept regular expressions: DocType, DestOrgName, SrcOrgName, DestQualifier, DestQualifierValue, SrcQualifier, and SrcQualifierValue.


Custom Counter Query Properties

When you create a new custom counter class instance, you provide values for properties that determine the query executed by the custom counter.

Values for the following query properties can be specified, when creating an instance of the MSBTS_CustomCounterSetting class:

  • Custom Counter Name. Name of the new class instance being created.

  • Source Organization. Name of the organization that is the source for the channel through which the document is processed, as defined in the BizTalk Messaging Management configuration.

  • Source Qualifier. Qualifier for the source organization identifier for the channel through which the document is processed.

  • Source Value. Value for the source organization identifier for the channel through which the document is processed.

  • Destination Organization. Name of the organization that is the destination for the channel through which the document is processed, as defined in the BizTalk Messaging Management configuration.

  • Destination Qualifier. Qualifier for the destination organization identifier for the channel through which the document is processed.

  • Destination Value. Value for the organization identifier defined in the BizTalk Messaging Management configuration as the destination for the channel through which the document is processed.

  • Document Type. Name of the root element from the document schema.

  • Time Interval. Interval of time, in seconds, over which to accumulate the custom counter value.

  • BizTalk Server Group Name. Name of the BizTalk Server group against which the custom counter query is to be executed.

For an example of programmatically setting these properties, see Creating a Custom Counter Using WMI and the Custom Counters sample.

Notes

  • In BizTalk Server 2002, organizations can be assigned an identifier alias. Identifiers consist of a name, qualifier, and value. When creating an organization, a default qualifier of OrganizationName is used along with a user-assigned name string as the identifier value. You can then create additional organization identifiers for specific tracking or routing purposes.

  • When tracking documents during processing, BizTalk Server records the qualifier and value for each channel source and destination organization. When creating a new custom counter class instance, it is possible to specify just the source and destination organization name or a qualifier-value pair. However, organization names and qualifier-value pairs cannot be specified at the same time.

  • When only the source and/or destination organization name is provided, the custom counter will include all documents that were processed through channels with any of the identifiers for the specified organization. When qualifier-value pairs are provided, only the documents processed by channels configured with those qualifier-value pairs are included.

  • To count only documents whose processing channel(s) had only the default qualifier-value pair configured, the qualifier should be OrganizationName and the value should be the name of the organization.

  • Wild-card expressions can be used for the following arguments when creating a new custom-counter class instance:
    • Source Organization

    • Source Qualifier

    • Source Value

    • Destination Organization

    • Destination Qualifier

    • Destination Value

    • Document Type


Custom Counters Validation

Validation of custom counters is optional and is provided through the IsValid method on the custom counter setting class, MSBTS_CustomCounterSetting.


Using Managing and Monitoring

This section provides task-specific information about how to manage and monitor by using Microsoft BizTalk Server 2002. Topics illustrate how to create and manipulate the BizTalk Server Administration objects by using WMI. It is highly recommended that you review the Understanding Managing and Monitoring topic as well.

The following topics are covered:

  • Creating an Event Consumer Using WMI

  • Creating a Custom Counter Using WMI

  • Handling WMI Errors


Creating an Event Consumer Using WMI

WMI provides a powerful event architecture that enables modifications in management information to be identified, aggregated, and associated with other management information, which can then be forwarded to local or remote management applications. Event handling and notification is a key benefit provided by WMI that provides a mechanism for identifying and dealing with hardware or software events and errors.

After an event occurs, a notification is delivered to one or more registered recipients, knows as event consumers. Event consumers can register to receive certain types of notifications. Event consumers register to receive notifications without any knowledge of how events and notifications are provided. To register, event consumers specify a filter that is created by using the WMI Query Language (WQL). The query describes the conditions under which the consumer receives the event notification.

In addition to DCOM interfaces, WMI supports a uniform scripting application programming interface (API) that gives applications and scripts access to the WMI provider on either a local computer or a remote computer.

This section shows the basic steps necessary to write a temporary WMI event consumer with Microsoft Visual Basic script, although some of the associated DCOM interfaces are mentioned.

This section contains the following topics:

  • Declaring Variables

  • Connecting to the Microsoft BizTalk Server Namespace

  • Creating the Event Object

  • Monitoring Events

Note

  • If you have Health Monitor installed (either from Microsoft Application Center 2000 or Microsoft BackOffice® Server), you can configure Health Monitor through its Microsoft Management Console (MMC) user interface (UI) (or its WMI class) to consume events.


Declaring Variables

To write an event consumer using WMI, you will need to obtain a locator object, a services object, an event object, and an object to represent a WMI class instance.

First, declare the variables, as shown in the following code:

Dim wbemLocat

Dim wbemSrvcs

Dim wbemEvent

Dim wbemObject

The locator object variable, wbemLocat, of type SwbemLocator, is used to connect to WMI. To connect to the "MicrosoftBizTalkServer" namespace under the Root namespace (Root/MicrosoftBizTalkServer), you set the services object variable, wbemSrvcs, of type SWbemServices. The event object variable, wbemEvent, of type SwbemEventSource, is needed to execute a query to receive events. To retrieve an event from the event query, you set the wbemObject variable of type SwbemObject.


Connecting to the Microsoft BizTalk Server Namespace

After you declare the variables, you need to retrieve the locator object. If you are using the scripting API, create a WbemScripting.SwbemLocator object, as shown in the following code:

Set wbemLocat = CreateObject("WbemScripting.SWbemLocator")

Note that the first step for any application using WMI is to retrieve a locator object. If you are using the DCOM interfaces in C/C++, you would retrieve an IWBEMLocator pointer by using the COCreateInstance method with the CLSID_WbemLocator class identifier, as shown in the following code:

IWbemLocator* piWMI = NULL;
HRESULT hr;

    hr = CoCreateInstance(
        CLSID_WbemLocator,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IWbemLocator,
        (LPVOID*) &piWMI
    );

Using the locator object and the ConnectServer method, you can request a connection to the WMI service. The following code attempts to connect to WMI by specifying the Root namespace on the local computer. In the following code, replace the string "ComputerName" with the name of the server that publishes the event:

Set wbemSrvcs = wbemLocat.ConnectServer("ComputerName", "root\MicrosoftBizTalkServer")

If Err.number is equal to 0, then the connection to the WMI namespace is established. Specify both the computer name and the namespace; otherwise, if these fields are left blank, you will be connected to the default namespace on the local computer.

The returned SWbemServices object provides a communication path to the SQL Server database that is used to store administrative objects.


Creating the Event Object

Now that you have connected to the "MicrosoftBizTalkServer" namespace, you need to create the event object. The following code generates an event object to receive event notifications:

Set wbemEvent = wbemSrvcs.ExecNotificationQuery("Select * from DocSuspendedEvent")

The filter used in the SWbemServices.ExecNotificationQuery method call is "Select * from DocSuspendedEvent", which is written using WQL. Like SQL queries, WQL queries can be refined to return a specific set of properties, or a subset of instances that satisfy some criteria.

When the consumer submits this query, it requests to be notified of all occurrences of the event represented by the DocSuspendedEvent class. This request includes a request for notification on all of the event's system and nonsystem properties. When the event provider submits the query, it registers support for generating notifications whenever an event represented by the DocSuspendedEvent class occurs.


Monitoring Events

Now that you have created the event object for the DocSuspendedEvent class, you need to set up the mechanism to monitor events represented by that class. First, set wbemObject of type SWbemObject to Empty, as shown in the following code:

wbemObject = Empty

Then, if an event is available, the SWbemEventSource.NextEvent method retrieves the event from an event query, as shown in the following code:

Set wbemObject = wbemEvent.NextEvent(Timeout)

The SWbemObject object supports generic properties and methods that apply to all WMI objects, as well as exposing the properties and methods of the object as dynamic automation properties and methods of this object.

Use the following code to retrieve the globally unique identifier (GUID) for the item in the suspended queue event:

EventSuspendedQueueWaitForEvent = wbemObject.Properties_.Item("stringSuspendedGuid").Value

If the wbemObject is not set to Empty, then the GUID for the item in the Suspended queue event is retrieved; otherwise; a time-out error occurs while waiting for the Suspended queue event.

Note that stringSuspendedGuid is a property of the DocSuspendedEvent class. The Properties_ property returns an SWbemPropertySet object that is a collection of the properties for the current class or instance, in this case the DocSuspendedEvent class. The Item method then retrieves an SWbemProperty from the collection, in this case the stringSuspendedGuid property.

For more information about WMI Application Programming in BizTalk Server, see Handling WMI Errors.


Creating a Custom Counter Using WMI

This section shows the basic steps necessary to create a custom counter using organizations, and to perform a Tracking database query.

This section contains the following topics:

  • Declaring Variables

  • Setting the Security Level

  • Setting the Query Properties

  • Creating or Updating the Custom Counter

  • Validating the Custom Counter

  • Executing the Custom Counter Query

The code examples in this section use Microsoft Windows Instrumentation (WMI) and Microsoft Visual Basic script.

For an example of how to create a custom counter using qualifier and value pairs instead of organizations, see the Custom Counters sample.


Declaring Variables

To write a custom counter using WMI, define the following constants:

Const wbemChangeFlagUpdateOnly = 1

Const wbemChangeFlagCreateOnly = 2

Const CUSTCOUNTER_SETTING_NAMESPACE = "MSBTS_CustomCounterSetting"

In addition, you will need to obtain a locator object, a services (or namespace) object, and objects to represent WMI class instances.

Declare the variables, as shown in the following code:

Dim WBEMLocator

Dim WBEMNameSpace

Dim objCustomCounterFactory

Dim objCustomCounterSetting

Dim objCustomCounter


Setting the Security Level

Before setting the security level, you need to connect to the "MicrosoftBizTalkServer" namespace under the Root namespace (Root/MicrosoftBizTalkServer), as shown in the following code:

Set WBEMLocator = CreateObject("WbemScripting.SWbemLocator")

Set WBEMNameSpace = WBEMLocator.ConnectServer(, "root/MicrosoftBizTalkServer")

Then, set the security level for the namespace, as show in the following code:

WBEMNameSpace = GetObject("Winmgmts:{impersonationlevel=impersonate}!root/" & "MicrosoftBizTalkServer")


Setting the Query Properties

Before setting the query properties, you need to create a new instance of a custom counter setting class, as shown in the following code:

Set objCustomCounterFactory = WBEMNameSpace.Get(CUSTCOUNTER_SETTING_NAMESPACE)

Set objCustomCounterSetting = objCustomCounterFactory.SpawnInstance_

After the call to SpawnInstance_, objCustomCounterSetting contains an instance of MSBTS_CustomCounterSetting. This class is used to create, delete, and update custom counters.

In this example, the custom counter query is based on the source and destination organizations. To set the query properties, set the properties of the MSBTS_CustomCounterSetting instance, as shown in the following code:

objCustomCounterSetting.Name = "My Custom Counter"

objCustomCounterSetting.SrcOrgName = "SourceOrg"

objCustomCounterSetting.DestOrgName = "DestinationOrg

objCustomCounterSetting.DocType = "PORequest"

objCustomCounterSetting.TimeInterval = 300

objCustomCounterSetting.GroupName = "BizTalk Server Group"

So, the custom counter will count the number of documents passing from the source organization ("SourceOrg") to the destination organization ("DestinationOrg") using a document schema with the root element "PORequest". Also, note that the custom counter will only query the Tracking database for document entries from the previous 300 seconds.


Creating or Updating the Custom Counter

After setting the query properties, you should create or update the custom counter setting.

To create the custom counter setting, specify the wbemChangeFlagCreateOnly flag, as shown in the following code:

objCustomCounterSetting.Put_(wbemChangeFlagCreateOnly)

To update the custom counter setting, specify the wbemChangeFlagUpdateOnly flag, as shown in the following code:

objCustomCounterSetting.Put_(wbemChangeFlagUpdateOnly)

Note

  • When calling the Put_ method to create or update the custom counter setting, the wbemChangeFlagCreateOrUpdate flag is not supported. Instead, you must specify either wbemChangeFlagCreateOnly or wbemChangeFlagUpdateOnly, depending on whether you want to create or update the custom counter setting.


Validating the Custom Counter

After setting the query properties and creating or updating the custom counter, you should validate your custom counter.

You can validate on the following properties:

  • Source Organization

  • Source Organization Identifier

  • Destination Organization

  • Destination Organization Identifier

  • BizTalk Server Group

Note

  • The document type is not validated, because the value of the document type is not always known until the actual document is received.

Validate the custom counter settings, as shown in the following code:

objCustomCounterSetting.IsValid bSrcOrg, bSrcOrgId, bDestOrg, bDestOrgId, bGroup

As an example, you can use a message box to ensure that your query properties are valid, as shown in the following code:

WScript.Echo "ValidityCheck: " & vbCrLf & _

"SrcOrg " & CStr(bSrcOrg) & vbCrLf & _

"SrcId " & CStr(bSrcOrgId) & vbCrLf & _

"DestOrg " & CStr(bDestOrg) & vbCrLf & _

"DestId " & CStr(bDestOrgId) & vbCrLf & _

"Group " & CStr(bGroup)


Executing the Custom Counter Query

To execute the custom counter query, you need to retrieve an instance on the MSBTS_CustomCounter class. Since both the custom counter setting Name property and the custom counter Name property are key properties and share the same value, you can use their Name properties to retrieve the custom counter object, as shown in the following code:

Set objCustomCounter = WBEMNameSpace.Get("MSBTS_CustomCounter.Name=""" & _

objCustomCounterSetting.Name & """")

After retrieving the custom counter object, you can query the MatchCount property to view the results of the query, as shown in the following code:

WScript.Echo "Counter Information: " & objCustomCounter.Name & vbCrLf & _

"Matching Documents: " & objCustomCounter.MatchCount


Handling WMI Errors

This section uses Microsoft Visual Basic code to illustrate how to determine whether a WMI method returns an error, and if so, how to decipher the meaning of the error.

First, you declare two variables: an SWbemLastError object to contain and manipulate error objects, and an array of String objects to contain the numerical value, parameter information, and text description of the error, as shown in the following code:

Dim objWMIError As SWbemLastError

Dim strError(0 To 2) As String

To determine whether WMI raises an error, check the Err object. If the Err object is not equal to 0, then an error has been raised. Then, you can try to set the SWbemLastError object to a new instance.

Note that the TypeName function is used to return information about the objWMIError variable. If it is equal to Nothing, error information is not available, and the attempt to create the error object has failed.

If the call succeeds and an error object returns, the status of the object is reset and the members of the string array are set to meaningful values, as shown in the following code:

If Err <> 0 Then

strError(0) = Hex(Err.Number)

Set objWMIError = New SwbemLastError

If TypeName(objWMIError) <> "Nothing" Then

strError(1) = objWMIError.ParameterInfo

strError(2) = objWMIError.Description

Else

Err.Clear

strError(1) = ""

strError(2) = ""

End If

Else

strError(0) = 0

strError(1) = ""

strError(2) = ""

End If


BizTalk Server Developer's Toolbox

This section uses Microsoft® Visual Basic®, C++, and Visual Basic script to provide a toolbox of solutions to common tasks encountered by BizTalk Server developers. These code examples are provided without robust error-handling functionality and should serve as an introduction to designing your own tools when working with BizTalk Server.

These code examples should not be used in a production environment.

This section contains the following topics:

  • BizTalk Messaging Services Tasks

  • BizTalk Orchestration Services Tasks

  • BizTalk Managing and Monitoring Tasks

  • Miscellaneous Tasks

Note that some of these solutions are not specific to BizTalk Server.


BizTalk Messaging Services Tasks

This section contains the following topics:

  • Clear BizTalk Messaging Configurations

  • Update Messaging Configurations with ADO Objects


Clear BizTalk Messaging Configurations

The following code clears the BizTalk Messaging Management database.

This example ClearBTMConfigurations method is written in Microsoft Visual Basic.

Sub ClearBTMConfigurations()

First, declare the variables, as shown in the following declaration:

    Dim Configuration, Obj, CurrObj, HomeOrgID

To delete all existing configurations, create a configuration object to access the messaging objects, as shown in the following code:

    Set Configuration = CreateObject("BizTalk.BizTalkConfig")

Then, loop through and delete all existing channels, as shown in the following code:

    Set Obj = Configuration.CreateChannel
    Set CurrObj = Configuration.Channels

    While Not CurrObj.EOF
        Obj.Load CurrObj(0)
        Obj.Remove
        CurrObj.MoveNext
    Wend

Loop through and delete all existing port groups, as shown in the following code:

    Set Obj = Configuration.CreatePortGroup
    Set CurrObj = Configuration.PortGroups
    While Not CurrObj.EOF
        Obj.Load CurrObj(0)
        Obj.Remove
        CurrObj.MoveNext
    Wend

Loop through and delete all existing ports, as shown in the following code:

    Set Obj = Configuration.CreatePort
    Set CurrObj = Configuration.Ports
    While Not CurrObj.EOF
        Obj.Load CurrObj(0)
        Obj.Remove
        CurrObj.MoveNext
    Wend

Loop through and delete all existing envelopes, as shown in the following code:

    Set Obj = Configuration.CreateEnvelope
    Set CurrObj = Configuration.Envelopes
    While Not CurrObj.EOF
        Obj.Load CurrObj(0)
        Obj.Remove
        CurrObj.MoveNext
    Wend

Loop through and delete all existing document definitions, as shown in the following code:

    Set Obj = Configuration.CreateDocument
    Set CurrObj = Configuration.Documents
    While Not CurrObj.EOF
        Obj.Load CurrObj(0)
        Obj.Remove
        CurrObj.MoveNext
    Wend

Loop through and delete all existing organizations, as shown in the following code:

    Set Obj = Configuration.CreateOrganization
    Set CurrObj = Configuration.Organizations
    While Not CurrObj.EOF
        Obj.Load CurrObj(0)

Note the home (default) organization identifier, as shown in the following code:

        If Obj.IsDefault Then

Ensure that the home organization is not deleted and that it is saved for removing aliases, as shown in the following code.

            HomeOrgID = Obj.Handle
        ElseIf Obj.Name = "SEED Test Organization" Then

Do not perform any action at this point; only ensure that the SEED organization is not deleted.

        Else
            Obj.Remove
        End If

        CurrObj.MoveNext
    Wend

Clear the home organization aliases, except for the default alias and the alias with the organization name, as shown in the following code:

    Obj.load HomeOrgID
    Set CurrObj = Obj.Aliases

Then, reset the default alias, as shown in the following code:

    Obj.SaveAlias Obj.GetDefaultAlias, "sName" & Now(), False, "sQual" & Now(), "sValue" & Now()

    CurrObj.MoveFirst
    While Not CurrObj.EOF
        If CurrObj("qualifier") = "OrganizationName"  Then
            Obj.SaveAlias CurrObj(0), "Organization", True, "OrganizationName", Obj.Name
            Obj.Save
        Else

        If CurrObj("qualifier") <> "SMTP" then Obj.RemoveAlias CurrObj(0)
        End If

        CurrObj.MoveNext
    Wend

Loop through and delete all existing home organization applications, as shown in the following code:

    Set CurrObj = Obj.Applications
    While Not CurrObj.EOF
        Obj.RemoveApplication CurrObj("id")
        CurrObj.MoveNext
    Wend

    Obj.save

Finally, set all objects to Nothing to release memory back to the system, as shown in the following code:

    Set Obj = Nothing
    Set CurrObj = Nothing
    Set Configuration = Nothing
End Sub


Update Messaging Configurations with ADO Objects

The following code uses the Microsoft ActiveX® Data Objects (ADO) returned by the BizTalk Messaging Configuration object model to select a subset of existing channels, and to modify the configurations of those channels. In this sample, all existing channels using an input document definition name of "Invoice" will be selected, their RetryCount property will be updated to six retries, and their RetryInterval property will be set to ten minutes.

This example UpdateRetry method is written in Microsoft Visual Basic Scripting Edition (VBScript).

Sub UpdateRetry()

First, declare the variables, as shown in the following declaration:

    Dim objConfig
    Dim objChannel
    Dim objDoc
    Dim objADO

Then, create the channel and document objects, as shown in the following code:

    Set objConfig = CreateObject("BizTalk.BizTalkConfig")
    Set objChannel = objConfig.CreateChannel
    Set objDoc = objConfig.CreateDocument

Obtain a reference to the Channels recordset containing all existing channels in the BizTalk Messaging Management database, as shown in the following code:

    Set objADO = objConfig.Channels

Loop through all records in the recordset and load each channel by using the Handle provided in the first field of the record. Load the InputDocument associated with each channel to obtain the document definition name, and compare it to the string "Invoice" to select the appropriate records. When a record is selected, update the RetryCount and RetryInterval properties and Save the new channel configuration. This logic is shown in the following code:

    Do While NOT objADO.EOF
        objChannel.Load(objADO.Fields.Item(0))
        objDoc.Load(objChannel.InputDocument)
        If objDoc.Name = "Invoice" Then
            objChannel.RetryCount = 6
            objChannel.RetryInterval = 10
            objChannel.Save
        End If
        objADO.MoveNext
    Loop

Finally, set all objects to Nothing to release memory back to the system, as shown in the following code:

    Set objChannel = Nothing
    Set objConfig = Nothing
    Set objDoc = Nothing
    Set objADO = Nothing
End Sub


BizTalk Orchestration Services Tasks

This section contains the following topic:

  • Access a Messaging Port


Access a Messaging Port

The following code accesses a messaging port in an XLANG schedule instance:

This example is in Microsoft Visual Basic:

Dim oSked As IWFWorkflowInstance
Dim oPort

Set oSked = GetObject("sked://localhost/C:\temp\MySchedule.skx")
Set oPort = oSked.Port("PortIn")

This example is in VBScript:

Set oSked = GetObject("sked://localhost/C:\temp\MySchedule.skx")
Set oPort = oSked.Port("PortIn")


BizTalk Managing and Monitoring Tasks

This section contains the following topic:

  • WMI Tasks


WMI Tasks

To ensure that your Visual Basic projects can access the Windows® Management Instrumentation (WMI) objects used in the following topics, you need to add the Microsoft WMI Scripting V1.1 Library in the Reference dialog.

Then, you declare the following WMI locator and services variables:

Public g_objLocator As SWbemLocator
Public g_objService As SWbemServices

In addition, the following constants should be defined:

Public Const GROUP_NAMESPACE = "MicrosoftBizTalkServer_Group"
Public Const MGMT_NAMESPACE = "MicrosoftBizTalkServer_MgmtDB"
Public Const SERVER_NAMESPACE = "MicrosoftBizTalkServer_Server"
Public Const RECVSVC_NAMESPACE = "MicrosoftBizTalkServer_ReceiveFunction"
Public Const QUEUE_NAMESPACE = "MicrosoftBizTalkServer_Queue"
Public Const WORKQ_NAMESPACE = "MicrosoftBizTalkServer_WorkQueue"
Public Const SCHEDULEDQ_NAMESPACE = "MicrosoftBizTalkServer_ScheduledQueue"
Public Const RETRYQ_NAMESPACE = "MicrosoftBizTalkServer_RetryQueue"
Public Const SUSPENDEDQ_NAMESPACE = "MicrosoftBizTalkServer_SuspendedQueue"

You make the connection to WMI with the following code:

Set g_objLocator = New SWbemLocator
Set g_objService = g_objLocator.ConnectServer(, "root/MicrosoftBizTalkServer")

This section contains the following topics:

  • Documents and WMI

  • Groups and WMI

  • BizTalk Messaging Management Database and WMI

  • Receive Services and WMI

  • Servers and WMI

  • Queues and WMI


Documents and WMI

The code examples in this section are useful when working with documents and interchanges. An interchange is a collection of one or more document instances that makes up a single transmission.

This section presents functions that work together to convert variant data from a document or interchange into a string.

This section contains the following topic:

  • Displaying the Contents of a Document or an Interchange


Displaying the Contents of a Document or an Interchange

When you use the ViewDocument or ViewInterchange methods of the MicrosoftBizTalkServer_SuspendedQueue class, you might need to convert the returned byte array into a readable format.

The following function takes a code page and variant data and returns a string:

Function ConvertViewDocument(ByVal varData As Variant, ByVal codepage As Long) As String
    Dim varData2() As Byte
    Dim i As Long
    Dim strTemp As String
    Dim Dom As New DOMDocument

    On Error Resume Next
    ReDim varData2(UBound(varData))
    For i = LBound(varData) To UBound(varData)
        varData2(i) = varData(i)
        Next

    If codepage = -1 Then
        strTemp = CStr(varData2)
        Call Dom.loadXML(strTemp)
        If Err <> 0 Then
            ConvertViewDocument = ""
        ElseIf Dom.parseError.errorCode <> 0 Then
            ConvertViewDocument = ""
        Else
            ConvertViewDocument = Dom.xml
        End If
    Else
        ConvertViewDocument = ConvertVarToBstr(varData2, codepage)
    End If
End Function

The ConvertViewDocument function uses the following function to convert the variant data into a string:

Public Function ConvertVarToBstr(ByRef varData As Variant, ByVal strCodePage As String) As String
    Dim stm As New ADODB.Stream

    Select Case UCase(TypeName(varData))
        Case "STRING"
            ConvertVarToBstr = varData
        Case "BYTE()"
            stm.Type = adTypeBinary
            stm.Open
            stm.Write varData
            stm.Position = 0
            stm.Type = adTypeText
            stm.Charset = GetCharset(strCodePage)
            ConvertVarToBstr = stm.ReadText
            .Close
        Case Else
            ConvertVarToBstr = ""
    End Select
End Function

The ConvertVarToBstr function uses the following private function to return a character set:

Private Function GetCharset(ByVal codepage As String)
    Select Case codepage
        Case 932
            GetCharset = "shift-jis"
        Case 1252
            GetCharset = "us-ascii"
        Case 160001
            GetCharset = "utf-8"
        Case 1200
            GetCharset = "unicode"
    End Select
End Function


Groups and WMI

The code examples in this section are useful when working with groups. Server groups are collections of individual servers that are centrally managed, configured, and monitored.

This section presents functions that create a group, delete a group, retrieve a group by name, and retrieve all groups.

This section contains the following topics:

  • Creating a Group

  • Deleting a Group

  • Retrieving a Group by Name

  • Retrieving All Groups


Creating a Group

The following function creates a group:

Public Function CreateGroup(ByVal strGroupName As String, _
                ByVal strDocTrackDbLogon As String, _
                ByVal strDocTrackDbName As String, _
                ByVal strDocTrackDbPassword As String, _
                ByVal strDocTrackDbServer As String, _
                ByVal strQueueDbLogon As String, _
                ByVal strQueueDbName As String, _
                ByVal strQueueDbPassword As String, _
                ByVal strQueueDbServer As String, _
                Optional ByVal lAdminCacheRefreshInterval As Long, _
                Optional ByVal strSMTPHost As String, _
                Optional ByVal strReliableMessagingReplyToURL As String, _
                Optional UseProxyServer As Boolean, _
                Optional strProxyName As String, _
                Optional lProxyport As Long, _
                Optional lLoggingPointState As Integer) As Boolean
    Dim objBTGroup As SWbemObject
    Dim objBTGroupInstance As SWbemObject

    On Error Resume Next
    Set objBTGroup = g_objService.Get(GROUP_NAMESPACE)
    Set objBTGroupInstance = objBTGroup.SpawnInstance_

    CreateGroup = True

    objBTGroupInstance.Name = strGroupName
    objBTGroupInstance.DocTrackDbLogon = strDocTrackDbLogon
    objBTGroupInstance.DocTrackDbName = strDocTrackDbName
    objBTGroupInstance.DocTrackDbPassword = strDocTrackDbPassword
    objBTGroupInstance.DocTrackDbServer = strDocTrackDbServer
    objBTGroupInstance.QueueDbLogon = strQueueDbLogon
    objBTGroupInstance.QueueDbName = strQueueDbName
    objBTGroupInstance.QueueDbPassword = strQueueDbPassword
    objBTGroupInstance.QueueDbServer = strQueueDbServer

    If strReliableMessagingReplyToURL <> "" Then
        objBTGroupInstance.ReliableMessagingReplyToURL = strReliableMessagingReplyToURL
    End If
    If lAdminCacheRefreshInterval <> 0 Then
        objBTGroupInstance.ConfigurationCacheRefreshInterval = lAdminCacheRefreshInterval
    End If

    objBTGroupInstance.UseProxyServer = UseProxyServer
    objBTGroupInstance.ProxyHost = strProxyName

    If lProxyport = 0 Then
        objBTGroupInstance.ProxyPort = lProxyport
    Else
        objBTGroupInstance.ProxyPort = lProxyport
    End If

    objBTGroupInstance.LoggingPointState = lLoggingPointState
    objBTGroupInstance.SMTPHost = strSMTPHost
    objBTGroupInstance.Put_ (wbemChangeFlagCreateOnly)

    If Err <> 0 Then
        CreateGroup = False
    End If
End Function


Deleting a Group

The following function deletes a group:

Public Function DeleteGroup(ByVal strGroupName As String) As Boolean
    On Error Resume Next
    DeleteGroup = True
    Call g_objService.Delete(GROUP_NAMESPACE & ".NAME=""" & strGroupName & """")

    If Err <> 0 Then
        DeleteGroup = False
    End If
End Function


Retrieving a Group by Name

The following function retrieves a group by name:

Public Function GetGroupByName(ByVal strGroupName As String) As Object
    Dim objBTGroup As SwbemObject

    On Error Resume Next
    Set GetGroupByName = Nothing
    Set GetGroupByName = g_objService.Get(GROUP_NAMESPACE & ".NAME=""" & strGroupName & """")

    If Err <> 0 Then
    End If
End Function


Retrieving All Groups

The following function retrieves all groups:

Public Function GetAllGroups() As SWbemObjectSet
    Dim objBTGroup As SWbemObject

    On Error Resume Next
    Set GetAllGroups = Nothing
    Set objBTGroup = g_objService.Get(GROUP_NAMESPACE)
    Set GetAllGroups = objBTGroup.Instances_

    If Err <> 0 Then
    End If
End Function


BizTalk Messaging Management Database and WMI

The code examples in this section are useful when working with the BizTalk Messaging Management database. The BizTalk Messaging Management database stores information for all server configurations, including group and server settings, and receive functions.

This section presents functions that create the BizTalk Messaging Management database and retrieve the BizTalk Messaging Management database.

This section contains the following topics:

  • Creating the BizTalk Messaging Management Database

  • Retrieving the BizTalk Messaging Management Database


Creating the BizTalk Messaging Management Database

The following function creates the BizTalk Messaging Management database:

Public Function CreateMgmtDB(ByVal strMgmtDbLogon As String, _
                            ByVal strMgmtDBPassword As String, _
                            ByVal strMgmtDBServer As String, _
                            ByVal strMgmtDBDatabase As String, _
                            ByVal strLocalServer As String) As Boolean
    Dim objBTSMgmt As SWbemObject
    Dim objBTSMgmtInstance As SwbemObject

    On Error Resume Next
    CreateMgmtDB = True
    Set objBTSMgmt = g_objService.Get(GROUP_NAMESPACE)
    Set objBTSMgmtInstance = objBTGroup.SpawnInstance_
        objBTSMgmtInstance.MgmtDbLogon = strMgmtDbLogon
        objBTSMgmtInstance.MgmtDBPassword = strMgmtDBPassword
        objBTSMgmtInstance.MgmtDbServer = strMgmtDBServer
        objBTSMgmtInstance.MgmtDbDatabase = strMgmtDBDatabase
        objBTSMgmtInstance.localserver = strLocalServer
        objBTSMgmtInstance.Put_ (wbemChangeFlagCreateOnly)

    If Err <> 0 Then
        CreateMgmtDB = False
    End If
End Function


Retrieving the BizTalk Messaging Management Database

The following function retrieves the BizTalk Messaging Management database:

Public Function GetMgmtDB(ByVal strLocalServer As String) As SWbemObject
    Dim objBTSMgmt As SWbemObject
    Dim objSet_BTSMgmt As SWbemObjectSet
    Dim objBTSMgmtInstance As SWbemObject

    On Error Resume Next
    Set GetMgmtDB = Nothing
    Set objBTSMgmt = g_objService.Get(MGMT_NAMESPACE)
    Set objSet_BTSMgmt = objBTSMgmt.Instances_

    If objSet_BTSMgmt.Count <> 1 Then
        Exit Function
    End If

    Set GetMgmtDB = objSet_BTSMgmt.Item(MGMT_NAMESPACE & ".LocalServer=""" & strLocalServer & """")
End Function


Receive Services and WMI

The code examples in the section are useful when working with receive services. You create receive services to process data.

This section presents functions that create a File receive service, delete a File receive service, retrieve a receive service by name, retrieve all receive services, and retrieve all receive services by group.

This section contains the following topics:

  • Creating a File Receive Service

  • Deleting a File Receive Service

  • Retrieving a Receive Service by Name

  • Retrieving All Receive Services

  • Retrieving All Receive Services by Group


Creating a File Receive Service

The following function creates a File receive service:

Public Function CreateReceiveService(ByVal strRecvSvcName As String, _
                        ByVal strGroupName As String, _
                        ByVal strProcessingServer As String, _
                        ByVal strFileMask As String, _
                        ByVal fProtocolType As ProtocolType, _
                        ByVal strPollingLoc As String, _
                        Optional ByVal strPassword As String, _
                        Optional ByVal strUsername As String, _
                        Optional ByVal strDocumentName As String, _
                        Optional ByVal strSourceID As String, _
                        Optional ByVal strSourceQualifier As String, _
                        Optional ByVal strDestinationID As String, _
                        Optional ByVal strDestinationQualifier As String, _
                        Optional ByVal lOpenness As Integer, _
                        Optional ByVal lPassthrough As Integer, _
                        Optional ByVal strChannelName As String, _
                        Optional fDisabled As Boolean, _
                        Optional ByVal strEnvelopeName As String, _
                        Optional ByVal strComment As String, _
                        Optional ByVal strPreProcessor As String) As Boolean
    Dim objBTSRecvSvc As SWbemObject
    Dim objBTSRecvSvcInstance As SWbemObject

    On Error Resume Next
    CreateReceiveService = True
    Set objBTSRecvSvc = g_objService.Get(RECVSVC_NAMESPACE)
    Set objBTSRecvSvcInstance = objBTSRecvSvc.SpawnInstance_

        objBTSRecvSvcInstance.Name = strRecvSvcName
        objBTSRecvSvcInstance.groupName = strGroupName
        objBTSRecvSvcInstance.Comment = strComment
        objBTSRecvSvcInstance.FilenameMask = strFileMask
        objBTSRecvSvcInstance.ProcessingServer = strProcessingServer
        objBTSRecvSvcInstance.ProtocolType = fProtocolType
        objBTSRecvSvcInstance.PollingLocation = strPollingLoc
        objBTSRecvSvcInstance.password = strPassword
        objBTSRecvSvcInstance.UserName = strUsername
        objBTSRecvSvcInstance.DocumentName = strDocumentName
        objBTSRecvSvcInstance.SourceID = strSourceID
        objBTSRecvSvcInstance.SourceQualifier = strSourceQualifier
        objBTSRecvSvcInstance.DestinationID = strDestinationID
        objBTSRecvSvcInstance.DestinationQualifier = strDestinationQualifier
        objBTSRecvSvcInstance.EnvelopeName = strEnvelopeName
        objBTSRecvSvcInstance.DisableReceiveFunction = fDisabled
        objBTSRecvSvcInstance.PreProcessor = strPreProcessor

    If lOpenness <> 0 Then
        objBTSRecvSvcInstance.OpennessFlag = lOpenness
    End If

    If lPassthrough <> 0 Then
        objBTSRecvSvcInstance.IsPassThrough = lPassthrough
    End If

    If strChannelName <> "" Then
        objBTSRecvSvcInstance.ChannelName = strChannelName
    End If

        objBTSRecvSvcInstance.Put_ (wbemChangeFlagCreateOnly)

    If Err <> 0 Then
        CreateReceiveService = False
    End If
End Function


Deleting a File Receive Service

The following function deletes a File receive service:

Public Function DeleteReceiveSvc(ByVal strRecvSvcName As String) As Boolean
    On Error Resume Next
    DeleteReceiveSvc = True
    Call g_objService.Delete(RECVSVC_NAMESPACE & ".NAME=""" & strRecvSvcName & """")

    If Err <> 0 Then
        DeleteReceiveSvc = False
    End If
End Function


Retrieving a Receive Service by Name

The following function retrieves a receive service by name:

Public Function GetReceiveFunctionByName(ByVal strRecvFunction As String) As SWbemObject
    On Error Resume Next
    Set GetReceiveFunctionByName = Nothing
    Set GetReceiveFunctionByName = g_objService.Get(RECVSVC_NAMESPACE & ".NAME=""" & strRecvFunction & """")

    If Err <> 0 Then
    End If
End Function


Retrieving All Receive Services

The following function retrieves all receive services:

Public Function GetAllReceiveServices() As SWbemObjectSet
    Dim objBTSRecvSvc As SWbemObject

    On Error Resume Next
    Set GetAllReceiveServices = Nothing
    Set objBTSRecvSvc = g_objService.Get(RECVSVC_NAMESPACE)
    Set GetAllReceiveServices = objBTSRecvSvc.Instances_

    If Err <> 0 Then
    End If
End Function


Retrieving All Receive Services by Group

The following function retrieves all receive services by group:

Public Function GetAllReceiveSvcsByGroup(ByVal strGroupName As String)
    Dim strWMIQuery As String

    On Error Resume Next
    strWMIQuery = "select * from " & RECVSVC_NAMESPACE & " where groupname= '" & strGroupName & "'"
    Set GetAllReceiveSvcsByGroup = g_objService.ExecQuery(strWMIQuery)

    If Err <> 0 Then
    End If
End Function


Servers and WMI

The code examples in this section are useful when working with servers. A server in a server group hosts the appropriate BizTalk Messaging Services functionality to manage document exchange between other servers and applications that are external to the BizTalk Server group.

This section presents functions that create a server, delete a server, start a server, stop a server, retrieve a server by name, retrieve all servers, and retrieve all servers by group.

This section contains the following topics:

  • Creating a Server

  • Deleting a Server

  • Starting a Server

  • Stopping a Server

  • Retrieving a Server by Name

  • Retrieving All Servers

  • Retrieving All Servers by Group


Creating a Server

The following function creates a server:

Public Function CreateServer(ByVal strServerName As String, _
                        ByVal strGroupName As String, _
                        ByVal lMaxWorkerThreadsPerProcessor As Long, _
                        ByVal lSchedulerWaitTime As Double) As Boolean
    Dim objBTSSvr As SWbemObject
    Dim objBTSSvrInstance As SWbemObject

    On Error Resume Next
    CreateServer = True
    Set objBTSSvr = g_objService.Get(SERVER_NAMESPACE)
    Set objBTSSvrInstance = objBTSSvr.SpawnInstance_

        objBTSSvrInstance.Name = strServerName
        objBTSSvrInstance.groupName = strGroupName
        objBTSSvrInstance.MaxWorkerThreadsPerProcessor = lMaxWorkerThreadsPerProcessor
        objBTSSvrInstance.SchedulerWaitTime = lSchedulerWaitTime

    Call objBTSSvrInstance.Put_(wbemChangeFlagCreateOnly)

    If Err <> 0 Then
        CreateServer = False
    End If
End Function


Deleting a Server

The following function deletes a server:

Public Function DeleteServer(ByVal strServerName As String) As Boolean
    On Error Resume Next
    DeleteServer = True
    Call g_objService.Delete(SERVER_NAMESPACE & ".NAME=""" & strServerName & """")

    If Err <> 0 Then
        DeleteServer = False
    End If
End Function


Starting a Server

The following function starts a server:

Public Function StartServer(ByVal strServerName As String) As Boolean
    Dim strWMIPath As String
    Dim objBTSSvrs As SWbemObject

    On Error Resume Next
    StartServer = True
    strWMIPath = SERVER_NAMESPACE & ".NAME=""" & strServerName & """"
    Set objBTSSvrs = g_objService.ExecMethod(strWMIPath, "StartServer")

    If Err <> 0 And Hex(Err) <> "80070420" Then
        StartServer = False
    Else
        Err.Clear
    End If
End Function

Note that if Err is not equal to 0, and the hexadecimal value of the error is not equal to 80070420, then the service was already running.


Stopping a Server

The following function stops a server:

Public Function StopServer(ByVal strServerName As String) As Boolean
    Dim strWMIPath As String
    Dim objBTSSvrs As SWbemObject

    On Error Resume Next
    StopServer = True
    strWMIPath = SERVER_NAMESPACE & ".NAME=""" & strServerName & """"
    Set objBTSSvrs = g_objService.ExecMethod(strWMIPath, "StopServer")

    If Err <> 0 And Hex(Err) <> "80070426" Then
        StopServer = False
    Else
        Err.Clear
    End If
End Function

Note that if Err is not equal to 0, and the hexadecimal value of the error is not equal to 80070426, then the service was not running.


Retrieving a Server by Name

The following function retrieves a server by name:

Public Function GetServerByName(ByVal strServerName As String) As SWbemObject
    On Error Resume Next
    Set GetServerByName = Nothing
    Set GetServerByName = g_objService.Get(SERVER_NAMESPACE & ".NAME=""" & strServerName & """")
End Function


Retrieving All Servers

The following function retrieves all servers:

Public Function GetAllServers() As SWbemObjectSet
    Dim objBTSSvrs As SWbemObject

    On Error Resume Next
    Set objBTSSvrs = g_objService.Get(SERVER_NAMESPACE)
    Set GetAllServers = objBTSSvrs.Instances_
End Function


Retrieving All Servers by Group

The following function retrieves all servers by group:

Public Function GetAllServersByGroup(ByVal strGroupName As String) As SWbemObjectSet
    Dim strWMIQuery As String

    On Error Resume Next
    strWMIQuery = "select * from " & SERVER_NAMESPACE & " where groupname= '" & strGroupName & "'"
    Set GetAllServersByGroup = g_objService.ExecQuery(strWMIQuery)
End Function


Queues and WMI

The code examples in this section are useful when working with queues. Queues are used to contain incoming and outgoing documents that are in various stages of routing and processing in BizTalk Server.

This section presents functions that retrieve queues by group and retrieve all queues.

This section contains the following topics:

  • Retrieving Queues by Group

  • Retrieving All Queues


Retrieving Queues by Group

This section illustrates functions that retrieve the Work, Retry, Suspended, or Scheduled queue by group.

The Work queue contains documents that are currently being processed by BizTalk Server. The following function retrieves the Work queue by group:

Public Function GetWorkQByGroup(ByVal strGroupName As String) As SWbemObjectSet
    Set GetWorkQByGroup = GetXXXXQByGroup(strGroupName, WORKQ_NAMESPACE)
End Function

The Retry queue contains documents that are being resubmitted for delivery and documents that are waiting for reliable messaging receipts. The following function retrieves the Retry queue by group:

Public Function GetRetryQByGroup(ByVal strGroupName As String) As SWbemObjectSet
    Set GetRetryQByGroup = GetXXXXQByGroup(strGroupName, RETRYQ_NAMESPACE)
End Function

The Suspended queue contains work items that have failed processing for a variety of reasons, including parsing errors, serialization errors, and failed transmissions. The following function retrieves the Suspended queue by group:

Public Function GetSuspendedQByGroup(ByVal strGroupName As String) As SWbemObjectSet
    Set GetSuspendedQByGroup = GetXXXXQByGroup(strGroupName, SUSPENDEDQ_NAMESPACE)
End Function

The Scheduled queue contains work items that have been processed by BizTalk Server and are waiting for transmission. The following function retrieves the Scheduled queue by group:

Public Function GetScheduledQByGroup(ByVal strGroupName As String) As SWbemObjectSet
    Set GetScheduledQByGroup = GetXXXXQByGroup(strGroupName, SCHEDULEDQ_NAMESPACE)
End Function

The following helper function is used by the previous functions to retrieve a given queue by group:

Public Function GetXXXXQByGroup(ByVal strGroupName As String, ByVal QueueNameSpace As String) As SWbemObjectSet
    Dim strWMIQuery As String

    On Error Resume Next
    strWMIQuery = "select * from " & QueueNameSpace & " where group= """ & strGroupName & """"
    Set GetXXXXQByGroup = g_objService.ExecQuery(strWMIQuery)
End Function


Retrieving All Queues

The following function retrieves all queues:

Public Function GetAllQueues() As SWbemObjectSet
    Dim objBTQueue As SWbemObject

    On Error Resume Next
    Set GetAllQueues = Nothing
    Set objBTQueue = g_objService.Get(QUEUE_NAMESPACE)
    Set GetAllQueues = objBTQueue.Instances_
End Function


Miscellaneous Tasks

This section contains the following topics:

  • Determine if BizTalk Server is Installed

  • Modify the XML Encoding

  • Retrieve BizTalk Server Product Information

  • Validate an XML Document


Determine if BizTalk Server is Installed

The following code determines if BizTalk Server is installed on the local machine.

Dim objService, objLocator, objConfig, strGroupName

Set objLocator = CreateObject("WbemScripting.SWbemLocator")

On Error Resume Next
Set objService = objLocator.ConnectServer(, "root/MicrosoftBizTalkServer")

PassFail "Unable to connect to BizTalk Server. Please verify that your BizTalk " & "Server is installed and functions properly."

Sub PassFail(strScope)
    If Err.Number <> 0 Then

MsgBox strScope & " Error: x" & Hex(Err.Number) & " Description: " & Err.Description & " Source: " & Err.Source

        Err.Clear
    Else

MsgBox "BizTalk Server appears to be installed."

    End If
End Sub


Modify the XML Encoding

BizTalk Server uses UTF-8 encoding in XML output files by default. Use the following Microsoft Visual Basic Scripting Edition (VBScript) code to specify a different encoding type:

set xmlObj = CreateObject("MSXML2.DomDocument.3.0")
wscript.echo wscript.arguments(1)

if wscript.arguments.count < 2 then
    wscript.echo "Usage: encoding.vbs XMLDocument Encoding"
    wscript.quit
end if

if xmlobj.load(wscript.arguments(0)) = False then
    wscript.echo "Unable to load the XML document."
    wscript.Echo "Error: " + xmlobj.ParseError.Reason + "Line: " + CStr(xmlobj.ParseError.Line)
    wscript.quit
end if

if (xmlObj.firstChild.nodeType = 7) and (xmlObj.firstChild.nodeName = "xml") then
    set child = xmlObj.firstChild
    xmlObj.removeChild child
end if

set pi = xmlObj.createProcessingInstruction("xml","version='1.0' encoding='" & wscript.arguments(1) & "'")
xmlObj.insertBefore pi, xmlObj.firstChild
xmlObj.save "newxml.xml"
wscript.echo "Done"

Notes

  • The "Usage" statement assumes that the script file containing this code is named encoding.vbs.

  • The first argument is the name of the XML document to be modified.

  • The second argument is a valid XML encoding value.

  • A new, modified version of the input XML file is created in the same folder with the name newxml.xml.

To run this script, open a Command Prompt window and use the following syntax:

C:\ > wscript encoding.vbs file.xml enctype

Where file.xml is the name of the XML file to be converted, and enctype is the encoding type to be used in the XML file.

To use this code with XML files created by BizTalk Server, you can create an application integration component (AIC) that incorporates similar XML document object model code. If you prefer to manually edit the file or run the script shown above, you can use the file transport protocol on the port to create the XML files to be converted.

Related Topics

Application Integration Components

Specify a transport address


Retrieve BizTalk Server Product Information

The following VBScript example uses the Microsoft Windows Installer Object Library to obtain information about BizTalk Server. In a Microsoft Visual Basic project, use the Microsoft Windows Installer Object Library (\system32\msi.dll).

Public objInstaller
Const gstrProductName = "Microsoft BizTalk Server 2002"

Sub Main()
    Dim guidProductCode

        On Error Resume Next
        Set objInstaller = CreateObject("WindowsInstaller.Installer")
        guidProductCode = GetProductGuid(gstrProductName)
        Wscript.echo "PRODUCT INFORMATION" & vbNewLine & vbNewLine & GetProductInfo(guidProductCode)
End Sub

Function GetProductGuid(sProductName)
    Dim sName
    Dim guidProductCode

        On Error Resume Next
        GetProductGuid = ""

        For Each guidProductCode In objInstaller.Products
            sName = objInstaller.ProductInfo(guidProductCode, "ProductName")

            If (LCase(sProductName) = LCase(sName)) Then
                GetProductGuid = CStr(guidProductCode)
                Exit For
            End If
        Next
End Function

Function GetProductInfo(guidProductCode)
    Dim s

    On Error Resume Next
    s = "ProductInfo for " & guidProductCode & vbNewLine
    s = s & vbNewLine
    s = s & "InstalledProductName: " & vbTab & objInstaller.ProductInfo(guidProductCode, "InstalledProductName") & vbNewLine
    s = s & "VersionString: " & vbTab & objInstaller.ProductInfo(guidProductCode, "VersionString") & vbNewLine
    s = s & "HelpLink:      " & vbTab & objInstaller.ProductInfo(guidProductCode, "HelpLink") & vbNewLine
    s = s & "HelpTelephone: " & vbTab & objInstaller.ProductInfo(guidProductCode, "HelpTelephone") & vbNewLine
    s = s & "InstallLocation: " & vbTab & objInstaller.ProductInfo(guidProductCode, "InstallLocation") & vbNewLine
    s = s & "InstallSource: " & vbTab & objInstaller.ProductInfo(guidProductCode, "InstallSource") & vbNewLine
    s = s & "InstallDate: " & vbTab & objInstaller.ProductInfo(guidProductCode, "InstallDate") & vbNewLine
    s = s & "Publisher: " & vbTab & objInstaller.ProductInfo(guidProductCode, "Publisher") & vbNewLine
    s = s & "LocalPackage: " & vbTab & objInstaller.ProductInfo(guidProductCode, "LocalPackage") & vbNewLine
    s = s & "URLInfoAbout: " & vbTab & objInstaller.ProductInfo(guidProductCode, "URLInfoAbout") & vbNewLine
    s = s & "URLUpdateInfo: " & vbTab & objInstaller.ProductInfo(guidProductCode, "URLUpdateInfo") & vbNewLine
    s = s & "VersionMinor: " & vbTab & objInstaller.ProductInfo(guidProductCode, "VersionMinor") & vbNewLine
    s = s & "VersionMajor: " & vbTab & objInstaller.ProductInfo(guidProductCode, "VersionMajor") & vbNewLine
    s = s & vbNewLine
    s = s & "Transforms: " & vbTab & objInstaller.ProductInfo(guidProductCode, "Transforms") & vbNewLine
    s = s & "Language: " & vbTab & objInstaller.ProductInfo(guidProductCode, "Language") & vbNewLine
    s = s & "ProductName: " & vbTab & objInstaller.ProductInfo(guidProductCode, "ProductName") & vbNewLine
    s = s & "AssignmentType: " & vbTab & objInstaller.ProductInfo(guidProductCode, "AssignmentType") & vbNewLine
    s = s & "PackageCode: " & vbTab & objInstaller.ProductInfo(guidProductCode, "PackageCode") & vbNewLine
    s = s & "Version:        " & vbTab & objInstaller.ProductInfo(guidProductCode, "Version") & vbNewLine
    s = s & "ProductIcon: " & vbTab & objInstaller.ProductInfo(guidProductCode, "ProductIcon") & vbNewLine
    GetProductInfo = s
End Function

Main


Validate an XML Document

The following code validates an XML document:

Dim xmlDoc As New Msxml2.DOMDocument

    xmlDoc.async = False
    xmlDoc.validateOnParse = True
    xmlDoc.Load "myXML.xml"


BizTalk Server Samples

Samples provided in the BizTalk Server SDK are located in the folder \Program Files\Microsoft BizTalk Server\SDK on the installation drive. These samples should not be used in a production environment.

Sample Requirements

The samples provided with BizTalk Server require one or more of the following applications:

  • Microsoft Visual Basic® is necessary to modify and compile the Visual Basic source files, such as .vbp files, that are included in the SDK. The Visual Basic runtime, VB6.exe, is also needed to run some of the executable files included in the SDK.

  • A compiler and source code editor, such as Microsoft Visual C++®, is necessary to modify and compile the C++ source files.

  • Microsoft Word or Wordpad is necessary to view some of the readme files that use a .doc file type extension.

  • An HTML browser, such as Microsoft Internet Explorer, is necessary to view some of the readme files that use an .htm file type extension.

This section contains the following topics:

  • BizTalk Messaging Services Code Samples

  • BizTalk Orchestration Services Code Samples

E-Procurement Sample


BizTalk Messaging Services Code Samples

Sample files are located in the Messaging Samples folder on the Microsoft BizTalk Server installation drive. Browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples on the installation drive to find the sample files. This is only a relative path. Depending on your installation of BizTalk Server 2002, you might need to modify this path.

  • Application Integration in Visual Basic

  • Application Integration in Visual C++

  • BizTalk Framework Developers' Toolkit

  • Configuration Assistant

  • Custom Counters

  • Custom Import Module

  • Custom Preprocessor in Visual Basic

  • Custom Preprocessor in Visual C++

  • Date Functoid

  • Date Functoid with .NET

  • Direct Integration

  • Distribution List

  • EDI and Receipts

  • EDI Introduction

  • Encryption and Decryption

  • Flat-File Delimited

  • Flat-File Positional

  • HTTP Receive Function

  • Mapping Twice

  • Message Queuing 4 MB Limit

  • Multi-part MIME Attachment

  • Pipeline Component in Visual Basic

  • Pipeline Component in Visual C++

  • Queue Sniffer

  • Receive Scripts

  • Refresh Messaging Manager

  • Reliable Messaging

  • Self Routing

  • Send To Remote Queue

  • Submitting Documents

  • Submitting Documents with Receipts

  • Submitting Documents to a Port Group

  • Suspended Queue Monitoring

  • Synchronous Orchestration Component

  • Tracking Database Tasks

  • Windows Management Instrumentation

Notes

  • When using C++, you need to add \Program Files\Microsoft BizTalk Server\SDK\Include to the include directory list.

  • Some of the samples have a dependency on the Pipecomplib.tlb file. For these samples, you need to add \Program Files\Common Files\Microsoft Shared\Enterprise Servers\Commerce to the include directory list.


Application Integration in Visual Basic

This sample demonstrates an application integration component (AIC) that implements the IBTSAppIntegration interface. The component provided in this sample receives a document that validates against the CommonPO.xml schema (provided by default in the BizTalk Server WebDAV repository), instantiates a schedule (provided with this sample) and passes the document to the schedule. The schedule gets the document and sends it to the file C:\temp\WFOut.txt.

For a related sample, see Application Integration in Visual C++.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\BTSAppIntegration\VB

User's Guide

Before running the sample, complete the following steps:

  1. Compile the Visual Basic component (this is optional because the DLL is provided with the sample).

  2. Register the component, its category IDs, and its setup configuration by running the script:

    cscript scenario.wsf //job:setup

    When prompted whether to register information from Affinity.reg, click Yes. The component progid is "BTSSamples_IBTSAppInt_VB AIC2Sched".

To run the sample:

  • Submit a document on the channel "BTSSamples_Channel_AIC2Sched" by using the script:

    cscript scenario.wsf //job:submit

    If the submission succeeds, the document appears in C:\temp\WFOut.txt.


Application Integration in Visual C++

This sample demonstrates an application integration component (AIC) that implements the IBTSAppIntegration interface by using the Active Template Library (ATL). The component provided in this sample receives a document that validates against the CommonPO.xml schema (provided by default in the BizTalk Server WebDAV repository) and returns the first element of the document.

For a related sample, see Application Integration in Visual Basic.

Note

  • This sample requires the Microsoft XML Parser (MSXML) version 3.0 or higher.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\BTSAppIntegration\VC\ATL

User's Guide

Before running the sample, complete the following steps:

  1. Compile the Visual C++ component.

  2. Set up the configuration by running the script:

    cscript scenario.wsf //job:setup

    The component progid is "BTSSamples.AtlIBTSAppInt".

To run the sample:

  • Submit a document on the channel "BTSSamples_Channel_ATL_IBTSAppInt_AIC" by using the script:

    cscript scenario.wsf //job:SubmitSync

    If the submission succeeds, it replies with the first element of the submitted document.


BizTalk Framework Developers' Toolkit

This sample demonstrates how to programmatically access the BizTalk Framework 2.0 tags in a message.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\BTFDevToolkit

User's Guide

Before running the sample, complete the following steps:

  1. Register one of the envelope objects using regsvr32. Depending on which version of the XML parser you have (version 2.0, version 2.6, or version 3.0), register BTFEnvelope20.dll, BTFEnvelope26.dll, or BTFEnvelope30.dll respectively. Note that only one of these libraries can be registered at a time because they share a common CLSID.
    2. Copy SchemaPluginGenerator.dll to $:\Microsoft Visual Studio\Common\MSDev98\AddIns and run regsvr32 on the DLL to register it. The AddIns folder path location can vary depending on where Microsoft Visual Studio® is installed.
  3. Copy the file pigen.ini to the same location as SchemaPluginGenertor.dll (the Visual Studio AddIns folder).

  4. Register the MSPlugin type library depending on which version of the XML parser you are running. Register the type library MSPlugin20.tlb, MSPlugin26.tlb, or MSPlugin30.tlb if you are using XML parser version 2.0, version 2.6, or version 3.0 respectively You can register this file by verifying, and updating if necessary, the TLB file location paths in Plugin2.reg. After the paths are correct, you can run the Plugin2.reg file by double-clicking it.

  5. Copy the following files to the Template\Classes folder in the Visual Basic program tree, $:\Microsoft Visual Studio\VB98\Template\Classes:
    • Microsoft Plugin class instance.cls

    • Microsoft Plugin collection instance.cls

    • Microsoft Plugin Main.cls

    Be sure that these files are not read-only.

  6. Copy the following file to the Template\Code folder in the Visual Basic program tree, $:\Microsoft Visual Studio\VB98\Template\Code:
    • modXMLHelper3.bas

    Be sure that this file is not read-only.

  7. Load the code generator. Open Visual Basic and run the Add-In manager. You should see the following available add-in: BTF Developers Toolkit Schema Plug-in Generator. Select the Loaded/Unloaded check box to load the add-in. It will appear in the Add-Ins drop-down menu.

To run the sample, you must have the following components installed:

  1. Visual Basic version 6.0 SP3 or SP4

  2. Microsoft XMLDOM typelib {F5078F18-C551-11D3-89B9-0000F81FE221}. There are components specifically targeted at all three versions (2.0, 2.6, and 3.0) of the Microsoft XML Parser (MSXML). Any one of these three versions of the document object model (DOM) will work. Read UsingPluginGenerator.doc for more information about the DOM-targeted versions of the BTFEnvelope component and the MSPlugin type library.

Programming Notes

The Resource Kit components consist of two core components and a type library:

  • Envelope object. This object provides programmatic access to the BTF2.0 header tags in the XML document, including management of the message body and the ability to add documents.

  • Plugin code generator. This takes an XDR schema and generates a "plugin" set of Microsoft Visual Basic COM components that provide programmatic access to the BODY tags in a BTF 2.0 message.

  • PlugIn2 interface. Exposed through the MSPlugin type library. This interface is implemented by the generated plugin component and called by the Envelope object. This interface is the link between the Envelope and the Plugin.

You can find further documentation on the Envelope and Plugin in the files UsingPluginGenerator.doc and EnvelopeAndPlugin.doc. The BizTalk Framework 2.0 (BTF) tag specification and the XML-Data Reduced (XDR) schema documentation can be found at http://msdn.microsoft.com/xml. It is highly recommended that you read the BTF specification and the UsingPluginGenerator documents before you use the components. You can obtain further architectural detail from the EnvelopeAndPlugin document.

Known Issues

  • The Plugin generator does not support XDR <group> structures when nested within another <group>. Generated code will work, but the embedded group will not have object model access code. In this scenario the IXMLDOMNode nodes will be available and the plugin is still usable and correct.

  • The generator will treat XDR order="one" attributes like order="many" because it does not know which child element will eventually be used. The programmer must set only one child element so that the resulting XML document will be valid.

  • The Visual Basic "Microsoft Plugin" template files located under $:\Microsoft Visual Studio\VB98\Template must not be read-only. If they are read-only, the generator will fail when adding modules to the targets Visual Basic project.

  • The BTFEnvelope object does not yet support BTF 2.0 Multipart MIME structures and Reliable Delivery structures. While this support is not directly developed into the component, the DOM nodes at each level are exposed so that they can easily be extended and customized.

  • The envelope can currently accept only one business document added to its body. Therefore it is not currently possible to add or access more than one business document nested in the body.


Configuration Assistant

This sample enables you to view all details of a BizTalk Server configuration and to export and import that configuration. The configuration export and import is completed as a package that includes all messaging objects such as document specifications, maps, custom parsers, serializers, and application integration components (AIC).

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\BTConfigAssistant

User's Guide

Detailed information is provided in the Readme.doc file located in the BTConfigAssistant folder.


Custom Counters

This sample allows you to create a custom counter that you can use to count the number of documents in the Tracking database (DTA) that match a specified set of criteria. This sample allows you to create two types of counters, one based on source and destination organization names, and one based on qualifier and value pairs. Each counter is validated after it is created.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Custom Counter

User's Guide

Before running the scripts, complete the following steps:

  1. On the C drive, create a folder called CustomCounterSample with two subfolders called SrcOrg and DestOrg.

  2. On the BizTalk Server installation drive, copy POReq.xml to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

  3. Run CustomCounterConfig.vbs to configure BizTalk Messaging Services.

To run documents through the DTA, copy and paste PORequest.xml to the C:\CustomCounterSample\SrcOrg folder. You should see an output file, Output.xml, in the C:\CustomCounterSample\DestOrg folder. Each time you do this an additional record will be tracked in the DTA.

To create a custom counter based on source and destination organization names, run CreateCustomCounter_Organizations.vbs.

To create a custom counter based on qualifier and value pairs, run CreateCustomCounter_Identifiers.vbs.

The first time you run each script, you will be creating an instance of the counter classes. When you run the script again to view the number of matching documents in the DTA, you will update the class.

To run the sample, you need to remove the read-only property from the sample data file, PORequest.xml.

Important

  • When calling the Put_ method to create or update the custom counter setting object, the wbemChangeFlagCreateOrUpdate flag is not supported. Instead, you must specify either wbemChangeFlagCreateOnly or wbemChangeFlagUpdateOnly, depending on whether you want to create or update the custom counter setting object. As a result, you need to update the source code of CreateCustomCounter_Organizations.vbs or CreateCustomCounter_Identifiers.vbs accordingly.

    For example, the following code from both the sample scripts creates the custom counter setting object:

    objCustomCounterSetting.Put_(wbemChangeFlagCreateOnly)

    To update the existing custom counter setting object, modify the code by specifying the wbemChangeFlagUpdateOnly flag, as shown in the following code:

    objCustomCounterSetting.Put_(wbemChangeFlagUpdateOnly)

    When you run the script again, the existing custom counter setting object will be updated.

    When the sample scripts are first installed, they are set up to create a custom counter setting object, in order to update the custom counter setting object and query the MatchCount property, you will need to update the scripts as specified above.

  • For the value of the MatchCount property to be consumed by Microsoft Operations Manager (MOM), the MOM DAS account must be a member of the BizTalk Server Administration group.

Programming Notes

This sample uses the MSBTS_CustomCounterSetting and MSBTS_CustomCounter Windows Management Instrumentation (WMI) classes. To locate the definitions of these classes, view the InterchangeProvSchema.mof file. The MatchCount property of MSBTS_CustomCounter is incremented each time a document runs through the DTA.


Custom Import Module

This sample creates a custom import module that imports a flat file and displays it in BizTalk Editor. The imported file is a delimited flat file exported from an SQL table. It is an ANSI file that uses "{CR}{LF}" as the row delimiter and comma as the column delimiter. The first line contains column names. The custom import module first creates a schema root called "SQLFile". It then parses the first line of the input file, extracts each column name, and creates each column as a text-only element under the root. The import module returns an XDR schema with BizTalk Server annotations.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\SampleImporter

User's Guide

To use this sample in BizTalk Editor, follow these steps:

  1. Register CustomImporter.dll (run regsvr32 CustomImporter.dll).

  2. Merge CustomImporter.reg (right-click CustomImporter.reg and then click Merge).

  3. In BizTalk Editor, on the Tools menu, click Import. The "Custom data" import module will appear in the "Select Import Module" window.

  4. Select 'sqlfile.txt'. The BizTalk Editor tree view window will display the schema structure that was created based on the input file.

  5. Select 'Blank.txt'. BizTalk Editor will display a dialog box that indicates a "column not found" error.

  6. Select 'FilewithWarning.txt'. BizTalk Editor will report warnings in the output window.

To remove this custom importer from BizTalk Editor, you need to unregister CustomImporter.dll by using the command: run regsvr32 /u CustomImporter.dll.


Custom Preprocessor in Visual Basic

This sample demonstrates a very simple implementation of a custom preprocessor to be used with a File receive function.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\VBCustPreProcessor

User's Guide

Before running the sample, complete the following steps:

  1. Compile the Visual Basic project into VBCustPreProcessor.dll.

  2. Register VBCustPreProcessor.dll by using regsvr32.

To run the sample, follow these steps:

  1. Set up a File receive function.

  2. Submit a document to BizTalk Server.

  3. Submit a document to the receive function.

Programming Notes

The Execute method simply loads the file into the XML DOM and then returns the XML data to BizTalk Server. The files should therefore always contain XML for the purposes of this sample.

This sample also demonstrates how to obtain context information from BizTalk Server although it does not actually use this context information during processing.


Custom Preprocessor in Visual C++

This sample demonstrates a very simple implementation of a custom preprocessor to be used with either File or Message Queuing receive functions.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\CustomPreProcessor

User's Guide

Before running the sample, complete the following steps:

  1. Compile the source files provided in this folder into CustomPreProcessorps.dll.

  2. Register CustomPreProcessorps.dll by using regsvr32.

To run the sample, follow these steps:

  1. Set up either a File receive function or a Message Queuing receive function.

  2. Submit a document to the receive function.

Programming Notes

When used by a File receive function, the Execute method simply loads the file into the XML DOM and then returns the XML data to BizTalk Server. The files should therefore always contain XML for the purposes of this sample.

When used by a Message Queuing receive function, if the input data contains an array of bytes, it is converted to a BSTR. Alternatively, if the input data contains a BSTR, it is converted to an array of bytes.

This sample also demonstrates how to obtain context information from BizTalk Server although it does not actually use this context information during processing.


Date Functoid

This sample creates a custom functoid that converts date formats. It converts a date in ISO format (generated from Date(), Time(), Now() in Visual Basic or from Date, Time, DateTime functoids) to a date in mm-dd-yyyy format. This sample is similar to the Date Functoid with .NET sample that is written in Visual C#™ .NET.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\SampleFunctoid

User's Guide

Before running the sample, complete the following steps:

  1. Register DateConversion.dll (run regsvr32 DateConversion.dll).

  2. Merge DateConversion.reg (right-click DateConversion.reg and then click Merge).

To run the sample in BizTalk Mapper:

  • Select the DateConversion functoid that appears in the functoid palette on the Date/Time tab.


Date Functoid with .NET

This sample creates a custom functoid that converts date formats. It converts a date in ISO format (generated from Date(), Time(), Now() in Visual Basic or from Date, Time, DateTime functoids) to a date in mm-dd-yyyy format. This sample is written in Visual C# .NET and shows how to write a functoid by using Microsoft .NET Framework. This sample is identical in functionality to the Date Functoid sample that is written in Visual Basic.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DateFunctoidNet

User's Guide

Before running the sample, complete the following steps:

  1. Register AssemblyPathFinder.dll by typing the following two commands:

    regasm AssemblyPathFinder.dll

    gacutil /i AssemblyPathFinder.dll

  2. Register AssemblyPathFinderProxy.dll by using the command:

    run regsvr32 AssemblyPathFinderProxy.dll

To run the sample with BizTalk Mapper, follow these steps:

  1. Run buildme.bat.

  2. Merge DateFunctoidNet.reg (right-click DateFunctoidNet.reg and then click Merge).

  3. The DateFunctoidNet functoid appears in the functoid palette on the Date/Time tab.

To remove this functoid from the BizTalk Mapper functoid palette, follow these steps:

  1. Run unreg.bat

  2. Delete the following key from the registry (by using regedit):

    HKEY_CLASSES_ROOT\CLSID\{722FF791-A0F8-42b9-B390-16C3F9238A5E}

Programming Notes

.NET Framework must be installed to run this sample.


Direct Integration

This sample demonstrates the use of IInterchange methods to submit documents to BizTalk Server. A user interface offers the ability to set parameters interactively before submitting a document.

The sample also contains the source code for a component that can be used to unpack binary buffers returned as BSTR. Buffers are converted to safe character arrays. The component is used by the main sample when saving data items from the Suspended queue to file.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DirectIntegration

User's Guide

Detailed information is provided in the Readme.doc file located in the DirectIntegration folder.


Distribution List

This sample consists of independent Visual Basic and Visual C++ samples that configure and run a DistributionList, or port group, scenario that sends documents to multiple trading partners. The two samples perform the same tasks and show how to implement those tasks by using two different programming languages.

The sample Submitting Documents to a Port Group contains related information.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\DistributionList

User's Guide

Before running the sample, complete the following steps:

  1. In the C++ sample, compile the source files DistributionList.cpp and DistributionList.h into an executable file.

  2. In the Visual Basic sample, create an executable file from the DistributionList project (.bas) file.

To run the sample:

  • Run the .exe file that you created in the preceding steps.

Programming Notes

In the C++ sample, the code shows how to set up the BizTalk Messaging Management database to submit a CommonPO document to a distribution list (port group).

The distribution list consists of two ports:

Port "SRC -> DST Port" wraps the input document in a BizTalk Framework (BTF) 2.0 envelope and drops the output to the file "%HOMEDRIVE%\DL_SRCtoDST.TXT".

Port "SRC -> APP2 Port" transports the input document and drops it to the file "%HOMEDRIVE%\DL_SRCtoAPP2.TXT".

After configuring the BizTalk Messaging Management database, the sample submits a CommonPO to BizTalk Server and then checks that there are no entries in the Suspended queue and that the expected number of entries was tracked in the Tracking database during the last Submit call.

In the Visual Basic sample, the code shows how to set up the BizTalk Messaging Management database to submit a CommonPO document to a distribution list.

The distribution list consists of two ports:

Port "SRC -> DST Port" wraps the input document in a BTF 2.0 envelope and drops the output to the file "%HOMEDRIVE%\DL_SRCtoDST.TXT".

Port "SRC -> APP2 Port" transports the input document and drops it to the file "%HOMEDRIVE%\DL_SRCtoAPP2.TXT".


EDI and Receipts

This sample demonstrates how BizTalk Server can be used to support inbound X12 purchase order (850) messages from a trading partner and generate outbound X12 receipts (997) for those messages.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\EDI and Receipts

User's Guide

The sample scenario involves an external trading partner (Fabrikam, Inc.) submitting X12 purchase order (850) documents to the home organization (Microsoft). The inbound X12 electronic data interchange (EDI) documents are mapped to XML format and transported to the internal recipient application (MOLP). To signal that the X12 850 has been received, the home organization sends a functional acknowledgement (997) document to the external organization. The outbound X12 997 receipt is generated from a canonical receipt format that is shipped with BizTalk Server.

This sample uses only file transport to simulate the scenario, and does not use BizTalk Orchestration Services. X12 EDI documents from Fabrikam are dropped in one directory, and the transformed XML documents and receipt documents are generated as output in other directories on the local file system.

Note

  • If you have run setup.cmd on the EDI Introduction sample, you must run the setup on this sample for the scenario to work correctly.

To run the sample, follow these steps:

  1. Run setup.cmd in the sample folder to configure the scenario.

    Configuration involves the creation of the following BizTalk Server objects:

    • Organizations: Microsoft (default organization), Fabrikam

    • Document Definitions: Fabrikam850, Microsoft997, MicrosoftPO-MOLP, MyCanonicalReceipt

    • Envelope: EDItoFabrikam

    • Port: EDIPortToFabrikam, PortToMOLP

    • Channel: Channel997toFabrikam, Channel850toFabrikam

    • Receive Function: EDIFiles

    Files are copied onto the C drive. Make the necessary modifications in setup.cmd and ConfigureEDIReceipts.vbs if the C drive does not exist.

  2. With BizTalk Server running, navigate to c:\EDIReceipts\ and copy the file Fabrikam850.edi into c:\ EDIReceipts\Fabrikam.

    This file should be consumed by BizTalk Server, transformed, and submitted to C:\EDIIntroduction\Microsoft as the file xmlpotomolp_%tracking_id%.xml, where %tracking_id% is a unique ID value. A receipt file named EDItofabrikam_%tracking_id%.edi is then submitted to C:\EDIIntroduction\Fabrikam\Receipts.

To walk through how the sample is prepared, follow these steps:

  • Set Up Organizations and Associated Identifiers

  • Set Up and Verify Document Specifications

  • Set Up Map for Converting X12 to XML

  • Create Document Definitions

  • Create EDI Envelope

  • Create Ports

  • Create Channels

  • Create File Receive Function

  • Run the Sample Scenario

Programming Notes

The schemas and maps for this sample are completed and are available for review. It is also recommended that you complete the EDI Introduction sample for additional background.


Set Up Organizations and Associated Identifiers

This section creates the home organization (Microsoft), the application within the home organization (MOLP), and the destination organization (Fabrikam). It also sets up the organizational identifiers that uniquely determine how the EDI interchange is processed.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. In the left frame, click Organizations, and then click Search Now.

  4. Ensure that Microsoft is the home organization.

    The home organization is indicated by (Default) next to the name. The dialog box that appears when you double-click the home organization should have three tabs.

  5. Click the Applications tab in the Organization Properties dialog box for Microsoft.

  6. Click Add, type MOLP, and then click OK.

  7. Click the Identifiers tab in the Organization Properties dialog box for Microsoft.

  8. Click Add, click Custom, and then type any name you like (for example, MyD&Bnumber) in the Custom text box.

  9. Enter 01 for Qualifier and 081466849 for Value. Click OK twice.

  10. To add the external trading partner organization Fabrikam, right-click the organization view window and click New Organization on the context menu.

  11. Click the Identifiers tab in the Organization Properties dialog box for Fabrikam.

  12. Click Add, click Custom, and then type any name you like in the Custom text box.

  13. Enter 01 for Qualifier and 0123456789 for Value. Click OK twice.


Set Up and Verify Document Specifications

In this section, you will set up, verify, and store to WebDAV the following document specifications:

  • schFabrikam850.xml - X12 850 purchase order sent from Fabrikam

  • schMicrosoftPO.xml - XML purchase order received by Microsoft

  • schMicrosoft997.xml - X12 997 receipt sent by Microsoft upon receiving 850

Note that the specification for a canonical receipt, CanonicalReceipt.xml, ships with BizTalk Server. It can be found in WebDAV in the Microsoft folder.

Set up EDI source specification

The file schFabrikam850.xml contains the document specification for the purchase order that is sent from Fabrikam. In this procedure you will examine an example X12 purchase order (850) that follows this specification (Fabrikam850.edi), validate the specification against a created test instance of the X12 850 (Fabrikam850NoEnvelope.edi), and store the specification to the WebDAV repository for future use.

  1. Using Notepad, open Fabrikam850.edi. (Right-click the file name, click Open With, and then select Notepad from the list of applications.) Leave Notepad active.

    You are looking at the EDI X12 purchase order (850). Note the delimiters needed to separate the records, fields, and subfields in the 850. They will be given in step 7 to validate the specification.

  2. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

  3. On the File menu, click Open, or use the toolbar icon to navigate to and select schFabrikam850.xml.

  4. Examine the specification. Select the nodes (for example, the root node X12_4010_850) and, on the View menu, click Expand Tree Items, or click the expand indicator (+).

  5. Using another instance of Notepad, open Fabrikam850NoEnvelope.edi. Compare this file with Fabrikam850.edi.

    As the file name indicates, Fabrikam850NoEnvelope.edi is the EDI X12 850 in step 1 with the header and trailer removed so that the BEG segment is at the top and the AMT segment followed by a carriage return/line feed is at the bottom. It will be used as a test validation instance of the EDI specification, because validation instances cannot contain envelope information.

  6. On the Tools menu, click Validate Instance and provide the file name Fabrikam850NoEnvelope.edi (in the same folder as other files used in this sample).

  7. In the Document Delimiters dialog box, specify ? (0x12), ~ (0x7e), and > (0x3e) for the Record, Field, and Subfield delimiters respectively. Click OK.

    If the instance test worked, the EDI will be transformed to XML and shown in the Output window at the bottom of BizTalk Editor, and the message "The document instance validation succeeded" will appear.

  8. On the File menu, click Store to WebDAV, and place the schema into the BizTalk Server WebDAV repository under the name schFabrikam850.xml.

Set up XML destination specification

The file schMicrosoftPO.xml contains the XML source specification for the purchase order that is received by Microsoft. Open this document, validate it, and store it to the WebDAV repository for future use.

  1. In BizTalk Editor, on the File menu, click Open, or use the toolbar icon to navigate to and select schMicrosoftPO.xml (in the same folder as other files used in this sample).

  2. On the Tools menu, click Validate Specification.

  3. On the File menu, click Store to WebDAV, and place the schema into the BizTalk Server WebDAV repository under the name schMicrosoftPO.xml.

Create receipt specification

An X12 functional acknowledgement (a 997) is sent from Microsoft to Fabrikam. The specification for this document, schMicrosoft977.xml, can be created from a template that is shipped with BizTalk Server.

  1. In BizTalk Editor, on the File menu, click New.

  2. In the New Document Specification dialog box, select X12, select 4010, and then select 997Schema.xml. Click OK.

  3. Select the document root node (X12_4010_997) and click the Reference tab in the right frame.

    The Receipt property on the Reference tab should be set to Yes to indicate that the specification is a receipt type.

  4. On the File menu, click Store to WebDAV, and then place the schema into the BizTalk Server WebDAV repository under the name schMicrosoft997.xml.


Set Up Map for Converting X12 to XML

The file mapFabrikam850toMicrosoftPO.xml specifies how the X12 source specification should be converted to the XML destination specification. Review and compile the map, and store it to WebDAV for future use. Note that no map needs to be constructed for the receipt response, because one is pre-built and included with BizTalk Server for this version of X12 (4010). A copy of this pre-built map (CanonicalReceiptTo4010-997.xml) is included in the same directory for reference.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Mapper.

  2. On the File menu, click Open, or use the toolbar icon to navigate to and select mapFabrikam850toMicrosoftPO.xml.

  3. On the Tools menu, click Compile Map, or press F5, or click the toolbar icon that is second from the right.

  4. Review the warnings that appear. Double-click a warning to see the problem that it refers to.

    The following types of warnings appear. Mapping will occur as expected even with these warnings, and they can be ignored.

    • "Warning: The required field 'X' has no incoming link or constant value"

      This type of warning can be ignored because the field's parent will not be created. Therefore the field itself cannot violate the validation criteria because it will not actually exist.

    • "Warning: The destination node 'X' has multiple source loop paths"

      This type of warning can be ignored in this case because the single occurrence of the input records in the instance will not cause a problem with the multiple loop paths. This map might not function as expected with document instances that differ greatly from the one in this sample.

    • "Warning: The destination node "X" has 3 input(s). The maximum number of possible inputs to this node is 1"

      This type of warning can be ignored because the mapper is not able to determine the presence of logical gating of the multiple inputs, which allows only one value to be selected from the multiple inputs.

  5. On the File menu, click Store to WebDAV, and then place the map into the BizTalk Server repository under the name mapFabrikam850toMicrosoftPO.xml.


Create Document Definitions

In this section, you will create the following document definitions:

  • Fabrikam850 - X12 850 purchase order sent from Fabrikam

  • MicrosoftPO-MOLP - XML purchase order received by Microsoft

  • MyCanonicalReceipt – Receipt document used to generate the outbound X12 997

  • Microsoft997 – Outbound X12 997 receipt sent by Microsoft upon receiving 850

Create EDI source document definition

In this procedure, you create the document definition Fabrikam850 for the Fabrikam X12 850 that is based on schFabrikam850.xml. Document tracking and selection criteria for the EDI document definition will be utilized.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the left frame, click Document Definitions, and then click Search Now.

  3. Right-click in the right frame and click New Document Definition on the context menu.

  4. For Document definition name type Fabrikam850.

  5. Select the Document specification check box.

  6. Click Browse and select schFabrikam850.xml from the repository list of schemas.

  7. Click the Global Tracking tab.

  8. Expand the BEG segment by clicking the expand indicator (+), select BEG03 (PO number), and then click Text to store this field for all instances processed through this document definition.

  9. Click the Selection Criteria tab.

  10. Click Add, type application_receiver_code for Name, type MAXCIM for Value, and then click OK.

  11. Repeat step 10 to create three more Selection Criteria name/value pairs:
    • application_sender_code / 0123456789

    • functional_identifier / PO

    • standards_version / 004010
  12. Click OK.

Create XML destination document definition

In this procedure, you create the document definition MicrosoftPO-MOLP for the XML purchase order that is received by Microsoft, based on schMicrosoftPO.xml. Document tracking will not be used in this case, and because this is not an EDI definition, defining the selection criteria is also not necessary.

  1. In BizTalk Messaging Manager, right-click in the Document Definitions right frame and click New Document Definition on the context menu.

  2. For Document definition name type MicrosoftPO-MOLP.

  3. Select the Document specification check box.

  4. Click Browse and select schMicrosoftPO.xml from the repository list of schemas.

  5. Click OK.

Create inbound (canonical) receipt document definition

When BizTalk Messaging Services on the home organization processes an inbound interchange from a trading partner, and receipts are required, the parser extracts header elements to generate a canonical receipt. In this procedure, you create the document definition MyCanonicalReceipt based on the canonical receipt specification CanonicalReceipt.xml that is shipped with BizTalk Server. This canonical receipt will then be used as the inbound document definition for the receipt channel (to be created) for delivery to Fabrikam. Neither document tracking nor selection criteria is necessary in defining MyCanonicalReceipt.

  1. In BizTalk Messaging Manager, right-click in the Document Definitions right frame and click New Document Definition on the context menu.

  2. For Document definition name type MyCanonicalReceipt.

  3. Select the Document specification check box.

  4. Click Browse and select CanonicalReceipt.xml from the Microsoft folder in the repository list of schemas.

  5. Click OK.

Create outbound receipt document definition

In this procedure, you create the document definition Microsoft997 based on schMicrosoft997.xml. This defines the outbound X12 997 receipt that Fabrikam expects from Microsoft. The receipt is generated by a mapping from MyCanonicalReceipt, with the map pre-built and included with BizTalk Server for this version of X12. Document tracking will not be utilized here, but defining the selection criteria is necessary.

  1. In BizTalk Messaging Manager, right-click in the Document Definitions right frame and click New Document Definition on the context menu.

  2. For Document definition name type Microsoft997.

  3. Select the Document specification check box.

  4. Click Browse and select schMicrosoft997.xml from the repository list of schemas.

  5. Click the Selection Criteria tab.

  6. Click Add, type application_receiver_code for Name and 0123456789 for Value, and then click OK.

  7. Repeat step 6 to create three more Selection Criteria name/value pairs:
    • application_sender_code / MAXCIM

    • functional_identifier / FA

    • standards_version / 004010
  8. Click OK.


Create EDI Envelope

This section will define the EDItoFabrikam envelope that will be used to wrap the X12 997 receipt from Microsoft to Fabrikam. Envelopes are needed whenever you are using non-XML documents.

  1. In BizTalk Messaging Manager, click Envelopes in the left frame and then click Search Now.

  2. Right-click in the right frame and click New Envelope on the context menu.

  3. Type EDItoFabrikam in the Name text box, click X12 on the Envelope Format drop-down menu, and then click OK.


Create Ports

This section will generate the two ports that are necessary for the inbound interchange and for the outbound receipt interchange.

Create port for internal application

This procedure will create the port PortToMOLP.

  1. In BizTalk Messaging Manager, click Messaging ports in the left frame and then click Search Now.

  2. Right-click in the right frame, click New Messaging Port on the context menu, and then click To Application.

  3. For Name enter PortToMOLP, leave Comments blank, and then click Next.

  4. The Applications option should be pre-selected. Click Name, select MOLP from the list, and then click OK.

  5. Create the directory c:\EDIReceipts\Microsoft\

    This is the location where Microsoft will receive the purchase order sent by Fabrikam and transformed to XML format.

  6. In the Primary Transport dialog box, click Browse, and then select File as the Transport Type.

  7. For the file name, type c:\EDIReceipts\Microsoft\xmlpotomolp_%tracking_id%.xml, click OK, and then click Next twice.

    The use of %tracking_id% allows each document to be saved to a unique file name.

  8. Clear the Create a channel for this messaging port check box, and then click Finish.

Create port for external trading partner

This procedure will create the port EDIPortToFabrikam.

  1. In BizTalk Messaging Manager, right-click in the Messaging ports right frame, click New Messaging Port on the context menu, and then click To an Organization.

  2. For Name enter EDIPortToFabrikam, leave Comments blank, and then click Next.

  3. The Organization option should be pre-selected. Click Browse, select Fabrikam from the list, and then click OK.

  4. Create the directory c:\EDIReceipts\Fabrikam\Receipts.

    This is the location where Fabrikam receives the X12 997 documents.

  5. In the Primary Transport dialog box, click Browse, and then select File as the Transport Type.

  6. For the file name, type c:\EDIReceipts\Fabrikam\Receipts\EDItofabrikam_%tracking_id%.edi, click OK, and then click Next.

    The use of %tracking_id% allows each document to be saved to a unique file name.

  7. Click EDItoFabrikam on the Envelope Information drop-down menu.

    Note that you can also create an envelope here if you forgot to do it earlier in Create EDI Envelope.

  8. Click Delimiters, enter the delimiters ~, *, and >, and then click OK.

    In this case, it does not matter what your delimiters are because there is no real business partner on the other end. In real scenarios, the delimiters are agreed upon between you and your business partners.

  9. In the Interchange Control Number dialog box, type a non-zero number.

  10. On the Organization Identifier drop-down menu, click 0123456789, and then click Next.

  11. Clear the Create a channel for this messaging port check box, and then click Finish.


Create Channels

This section will create the two channels for the inbound purchase order and outbound receipt interchanges. Note that the outbound receipt channel must be created first.

Create channel for outbound receipt

This procedure will create the receipt channel Channel997toFabrikam, with MyCanonicalReceipt as the inbound document definition and Microsoft997 as the outbound document definition. A pre-built map that is shipped with BizTalk Server (CanonicalReceiptTo4010-997.xml) will be used to transform the two definitions.

  1. Right-click EDIPortToFabrikam, click New Channel, and then click From an Application.

  2. For Name type Channel997toFabrikam.

  3. Select the This is a receipt channel check box, and click Next.

  4. The Application option should be pre-selected. Select MOLP from the drop-down list of application names.

  5. Select the 081466849 qualifier from the drop-down list, and then click Next.

  6. Under Inbound Document Definition Name click Browse, select the document definition called MyCanonicalReceipt, click OK, and then click Next.

  7. Under Outbound Document Definition Name click Browse, select the document definition called Microsoft997, and then click OK.

  8. The Map Inbound Document check box should be pre-selected. Click Browse to choose the map CanonicalReceiptTo4010-997.xml in the Microsoft folder of the WebDAV repository, click OK, and then click Next.

  9. Select any document storage options that interest you for the purpose of viewing in the BizTalk Document Tracking (see Start menu), and then click Next.

  10. Type an integer value in the Group Control Number text box.

    The value is not important, but you will note that repeated document flows through this channel will result in serially incremented values for this number.

  11. Click Finish.

Create channel for inbound purchase order

This procedure will create the channel Channel850toMOLP that will use Channel997toFabrikam as its associated receipt channel.

  1. In the left frame of BizTalk Messaging Manager, click Messaging ports, and then click Search Now.

  2. Right-click PortToMOLP, click New Channel, and then click From an Organization.

  3. For Name type Channel850toMOLP, and then click Next.

  4. The Organization option should be pre-selected. Click Browse, choose Fabrikam from the drop-down list, and then click OK.

  5. Select the Generate Receipt check box at the bottom of the dialog box.

  6. Click Browse, select Channel997toFabrikam, click OK, and then click Next.

  7. Under Inbound Document Definition Name, click Browse, select Fabrikam850, click OK, and then click Next.

  8. Under Outbound Document Definition Name, click Browse, select MicrosoftPO-MOLP, and then click OK.

  9. The Map Inbound Document check box should be pre-selected. Click Browse, select mapFabrikam850toMicrosoftPO.xml from the maps repository, click OK, and then click Next.

  10. Select any document storage options that interest you for the purpose of viewing in the BizTalk Document Tracking (see Start menu), click Next, and then click Finish.


Create File Receive Function

This section will create the File receive function EDIFiles for picking up Fabrikam purchase orders to send to Microsoft.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand the Microsoft BizTalk Server 2002 node in the left frame tree until the Queues and Receive Functions nodes are fully expanded.

  3. Add a new File receive function either by clicking the Receive Functions node and choosing Action | New | File Receive Function from the menu bar or by right-clicking the Receive Functions node and clicking New | File Receive Function on the context menu.

  4. Type EDIFiles for Name. Comments can be left blank.

    The machine you are working on should be pre-selected in the drop-down list titled Server on which.

  5. Type *.EDI in the File type to poll for text box.

  6. Verify the existence of the directory c:\EDIReceipts\Fabrikam.

    This is the location where Fabrikam will drop the X12 850 documents to be sent to Microsoft.

  7. Type c:\EDIReceipts\Fabrikam in the Polling Location text box.

  8. Click Advanced. In the Channel Name drop-down list, select Channel850toMOLP, and leave the defaults in the other data items.

  9. Click OK to close the Advanced dialog box, and then click OK to close the Add a File Receive Function dialog box.


Run the Sample Scenario

  1. The sample is run by placing the X12 instance Fabrikam850.edi into the Fabrikam folder and observing XML output to the Microsoft folder and the EDI receipt output to the Fabrikam/Receipts folder.

  2. Verify that the BizTalk service is running by making sure that a green arrow appears on your server icon in the BizTalk Server Administration MMC (server is immediately below Receive Functions in the tree); right-click the icon and click Start on the context menu if no green arrow is displayed.

  3. Copy Fabrikam850.edi to c:\EDIReceipts\Fabrikam and wait.

  4. Open the c:\EDIReceipts\Microsoft folder and look for a file called xmlpotomolp_%tracking_id%.xml, where the %tracking_id% symbol will be replaced with a GUID value.

  5. Open the c:\EDIReceipts\Fabrikam\Receipts folder and look for a file called EDItofabrikam_%tracking_id%.edi, where the %tracking_id% symbol will be replaced with a GUID value.


EDI Introduction

This sample demonstrates how to configure BizTalk Server to support XML documents flowing outbound from the home organization to an external trading partner using the EDI X12 855 document format.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\EDI Introduction

User's Guide

An internal application (MOLP) of the home organization (Microsoft) submits XML documents to BizTalk Server. These files are then mapped to an X12 EDI format and transported to the recipient trading partner (Fabrikam).

This sample uses only file transport to simulate the scenario, and does not use BizTalk Orchestration Services. XML documents from Microsoft are dropped in one directory, and the transformed X12 EDI documents are generated as output in another directory on the local file system.

Note

  • If you have run setup.cmd on the EDI and Receipts sample, you must run setup.cmd again on this sample for the scenario to work correctly.

To run the sample, follow these steps:

  1. Run setup.cmd in the sample directory to configure the scenario.

    Configuration involves the creation of the following BizTalk Server objects:

    • Organizations: Microsoft (default organization), Fabrikam

    • Document Definitions: Fabrikam855, MicrosoftPOAck

    • Envelope: EDItoFabrikam

    • Port: EDIPortToFabrikam

    • Channel: Channel855toFabrikam

    • Receive Function: XMLAcks

    Files are copied onto the C drive. Make the necessary modifications in setup.cmd and ConfigureEDI.vbs if the C drive does not exist.

  2. With BizTalk Server running, navigate to c:\EDIIntroduction\ and copy the file MOLPpoAck.xml into c:\EDIIntroduction\Microsoft.

    This file should be consumed by BizTalk Server, transformed, and submitted to C:\EDIIntroduction\Fabrikam as the file EDItoFabrikam_%tracking_id%.edi, where %tracking_id% is a unique ID value.

To walk through how the sample is prepared, follow these steps:

  • Set Up Organizations and Associated Identifiers

  • Set Up Source Specification

  • Set Up Destination Specification

  • Set Up Map for Converting XML to X12

  • Create Document Definition for Microsoft

  • Create Document Definition for Fabrikam

  • Define EDI Selection Criteria for Fabrikam

  • Create EDI Envelope

  • Create Port for Delivering EDI to Fabrikam

  • Create Channel from Microsoft to Fabrikam

  • Create File Receive Function

  • Run the Sample Scenario

  • Troubleshooting

Programming Notes

Electronic data interchange (EDI) is a set of standards for controlling the exchange of business documents (such as purchase orders and invoices) between computers. Although standardization efforts for EDI formats began in the 1960s, the expensive setup and operational costs of EDI server systems and the somewhat cryptic EDI document formats limited its use.

BizTalk Server supports the EDIFACT standard adopted in 1987 by the International Organization for Standardization (ISO) as well as the older X12 standard used primarily for American domestic trade. This sample goes through the transmission of a purchase order acknowledgement from Microsoft to Fabrikam using the X12 standard.

The schemas and maps for this sample are completed and are available for review to get a better understanding.


Set Up Organizations and Associated Identifiers

This section creates the home organization (Microsoft), the application within the home organization (MOLP), and the destination organization (Fabrikam). It also sets up the organizational identifiers that uniquely determine how the EDI interchange is processed.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. In the left frame, click Organizations, and then click Search Now.

  4. Verify that Microsoft is the home organization.

    The home organization is indicated by (Default) next to the name. The dialog box that appears when you double-click the home organization should have three tabs.

  5. Click the Applications tab in the Organization Properties dialog box for Microsoft.

  6. Click Add, type MOLP, and then click OK.

  7. Click the Identifiers tab in the Organization Properties dialog box for Microsoft.

  8. Click Add, click Custom, and type any name you like (for example, MyD&Bnumber) in the Custom box.

  9. Enter 01 for Qualifier and 081466849 for Value. Click OK twice.

  10. Add the external trading partner organization Fabrikam by right-clicking the organization view window and clicking New Organization on the context menu.

  11. Click the Identifiers tab in the Organization Properties dialog box for Fabrikam.

  12. Click Add, click Custom, and type any name you like in the Custom box

  13. Enter 01 for Qualifier and 0123456789 for Value. Click OK twice.


Set Up Source Specification

The file schMicrosoftPOAck.xml contains the XML source specification for the purchase order acknowledgement that is sent from Microsoft. Look at this document, validate it against an instance (MOLPpoAck.xml), and store it to the WebDAV repository for future use.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

  2. On the File menu, click Open, or use the toolbar icon to navigate to and select schMicrosoftPOAck.xml.

  3. Examine the specification by clicking the nodes (for example, the root node MicrosoftPOAck) and clicking Expand Tree Items on the View menu or clicking the expand indicator (+).

  4. On the Tools menu, click Validate Instance and provide the file name MOLPpoAck.xml (in the same folder as other files used in this sample).

    The message "The document instance validation succeeded" is shown if the instance test worked.

  5. On the File menu, click Store to WebDAV and place the schema into the BizTalk Server repository under the name schMicrosoftPOAck.xml.


Set Up Destination Specification

The file schFabrikam855.xml contains the specification for the X12 version release 4010 purchase order acknowledgement (855) that Fabrikam expects to receive. Review this document, validate the specification, and store it to the WebDAV repository for future use.

  1. In BizTalk Editor, open schFabrikam855.xml and expand the specification tree as before.

  2. On the Tools menu, click Validate Specification.

  3. On the File menu, click Store to WebDAV and place the specification into the BizTalk Server WebDAV repository under the name schMicrosoftPOAck.xml.


Set Up Map for Converting XML to X12

The file mapMicrosoftPOAcktoFabrikam855.xml specifies how the XML source specification should be converted to the X12 destination specification. Review and compile the map, and store it to WebDAV for future use.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Mapper.

  2. On the File menu, click Open, or use the toolbar icon to navigate to and select mapMicrosoftPOAcktoFabrikam855.xml.

  3. On the Tools menu, click Compile Map, or press F5, or click the toolbar icon that is second from the right.

  4. Review warnings.

    One type of warning appears: "Warning: The required field 'X' has no incoming link or constant value." Mapping will occur as expected even with this warning. It can be ignored because the field's parent will not be created, and therefore the field itself cannot violate the validation criteria because it will not actually exist.

  5. On the File menu, click Store to WebDAV, and place the map into the BizTalk Server repository under the name mapMicrosoftPOAcktoFabrikam855.xml.


Create Document Definition for Microsoft

In this procedure, you create a document definition MicrosoftPOAck for the Microsoft purchase order acknowledgement that is based on schMicrosoftPOAck.xml.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. In the left frame, click Document Definitions, and then click Search Now.

  3. Right-click in the right frame and click New Document Definition on the context menu.

  4. Type MicrosoftPOAck in the Document definition name box.

  5. Select the Document specification check box.

  6. Click Browse and select schMicrosoftPOAck.xml from the repository list of schemas.

  7. Click OK.


Create Document Definition for Fabrikam

In this procedure, you create a document definition Fabrikam855 for the Fabrikam X12 855 based on schFabrikam855.xml. A document definition for EDI also involves specifying the selection criteria, which is the subject of the next section.

  1. Right-click in the right frame of BizTalk Messaging Manager and click New Document Definition on the context menu.

  2. Type Fabrikam855 in the Document definition name box.

  3. Select the Document specification box.

  4. Click Browse and select schFabrikam855.xml from the repository list of schemas.

  5. Click OK.


Define EDI Selection Criteria for Fabrikam

The selection criteria is a list of name/value pairs that will allow the BizTalk messaging engine to uniquely identify the appropriate document definition for an EDI document. This is necessary because multiple EDI documents can be contained in a single interchange and multiple document types can be mixed within an interchange.

  1. Click the Selection Criteria tab for the Fabrikam855 document definition.

  2. Click Add. For Name, type application_receiver_code, for Value, type 0123456789, and then click OK.

  3. Repeat step 2 to create three more Selection Criteria name/value pairs:
    • application_sender_code / MAXCIM

    • functional_identifier / PR

    • standards_version / 004010
  4. Click OK to complete the document definition.


Create EDI Envelope

This section will define the EDItoFabrikam envelope. Envelopes are needed whenever you are using non-XML documents. A particular envelope is associated with a particular type of document (for example, X12), and contains information that the BizTalk messaging engine needs to route the document.

  1. In BizTalk Messaging Manager, click Envelopes in the left frame, and then click Search Now.

  2. Right-click in the right frame and click New Envelope on the context menu.

  3. Type EDItoFabrikam in the Name box, choose X12 from the Envelope Format drop-down list, and then click OK.


Create Port for Delivering EDI to Fabrikam

This procedure will create the port EDIPortToFabrikam.

  1. In BizTalk Messaging Manager, click Messaging ports in the left frame and then click Search Now.

  2. Right-click in the right frame, point to New Messaging Port, and click To an Organization.

  3. Type EDIPortToFabrikam in the Name box, leave Comments blank, and then click Next.

  4. The Organization option button should be pre-selected. Click Browse to select the organization name Fabrikam from the list, and then click OK.

  5. Create the directory c:\EDIIntroduction\Fabrikam\. This will be the location where Fabrikam receives the X12 855 documents.

  6. In the Primary Transport dialog box, click Browse, and choose File as the Transport Type.

  7. Type (after file://) c:\EDIIntroduction\Fabrikam\EDItofabrikam_%tracking_id%.edi as the file name, click OK, and then click Next.

    The use of %tracking_id% allows each document to be saved to a unique file name.

  8. Under Envelope Information, select EDItoFabrikam in the drop-down list.

    Note

    • You can also create an envelope at this point, if you did not do it previously in Create EDI Envelope.
  9. Click Delimiters and type the delimiters ~, *, and >. Click OK.

    In this case, it does not matter what your delimiters are because there is no real business partner on the other end. In real scenarios, the delimiters are agreed upon between you and your business partners.

  10. In the Interchange Control Number dialog box, type a non-zero number.

  11. Under Organization Identifier select the 0123456789 ID from the drop-down list, and then click Next.

  12. Clear the Create a channel for this messaging port check box, and click Finish.


Create Channel from Microsoft to Fabrikam

This procedure will create the channel Channel855toFabrikam.

  1. Right-click the EDIPortToFabrikam created previously, and click New Channel | From an Application.

    Alternatively, you could leave the Create a channel for this messaging port check box selected at the end of the New Messaging Port dialog

  2. For Name type Channel855toFabrikam, and then click Next.

  3. The Application option button should be pre-selected. Choose MOLP from the drop-down list of application names.

  4. Select the 081466849 qualifier from the drop-down list, and then click Next.

  5. Under Inbound Document Definition Name click Browse and select the document definition MicrosoftPOAck, click OK, and then click Next.

  6. Under Outbound Document Definition Name click Browse and select the document definition Fabrikam855, and then click OK.

  7. The Map Inbound Document check box should be pre-selected. Click Browse and choose MicrosoftPOAcktoFabrikam855.xml from the maps repository, click OK, and then click Next.

  8. Select any document storage options that interest you for the purpose of viewing in BizTalk Document Tracking (see Start menu), and then click Next.

  9. Type an integer value in the Group Control Number box.

    The value is not especially important. You will see that repeated document flows through this channel will result in serially incremented values for this number.

  10. Click Advanced, click the Envelope tab, and then click Properties. Review the dialog box where you will access the values to be used when creating the interchange envelope (no changes to these values are necessary for the sample).

  11. Click Finish.


Create File Receive Function

This section will create the File receive function XMLAcks for Microsoft documents.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand the Microsoft BizTalk Server 2002 node in the left frame tree until the Queues and Receive Functions nodes are fully expanded.

  3. To add a new File receive function, click the Receive Functions node.

  4. On the Action menu, point to New and click File Receive Function.

  5. Type XMLAcks in the Name box. Comments can be left blank.

    The machine you are working on should be pre-selected in the drop-down list titled Server on which.

  6. Type *.XML in the File type to poll for box.

  7. Create the directory c:\EDIIntroduction\Microsoft

    This is the location where Microsoft will drop the XML documents to be sent to Fabrikam.

  8. Type c:\EDIIntroduction\Microsoft in the Polling Location box.

  9. Click Advanced. In the Channel Name drop-down list, select Channel855toFabrikam, and leave the defaults in the other data items.

  10. Click OK to close the Advanced dialog box, and then click OK to close the Add a File Receive Function dialog box.


Run the Sample Scenario

The sample is run by placing the XML instance MOLPpoAck.xml into the Microsoft folder and observing the EDI output to the Fabrikam folder.

  1. Verify that the BizTalk service is running by making sure that a green arrow appears on your server icon in the BizTalk Server Administration MMC (the server is immediately below Receive Functions in the tree); right-click the icon and click Start on the context menu if no green arrow is displayed.

  2. Copy MOLPpoAck.xml to c:\EDIIntroduction\Microsoft.

  3. Open the c:\EDIIntroduction\Fabrikam folder and look for a file called EDItofabrikam_%tracking_id%.edi (from step 7 of "Create Port for Delivering EDI to Fabrikam"), where the %tracking_id% symbol is replaced with a GUID value.


Troubleshooting

If the MOLPpoAck.xml file is not picked up and deleted from c:\EDIIntroduction\Microsoft after a reasonable time period, check that the receive function XMLAcks in BizTalk Server Administration is correctly configured by right-clicking on the receive function and clicking Properties. Also make sure that the Disable receive function check box is cleared.

If MOLPpoAck.xml is picked up but there is no output in the c:\EDIIntroduction\Fabrikam directory, check the Suspended queue in BizTalk Server Administration for the error description.


Encryption and Decryption

This sample walks through the process of setting up a secure document exchange between two trading partners. This sample demonstrates the use of digital certificates to:

  • Encrypt an outgoing document

  • Sign an outgoing document

  • Decrypt an incoming document

  • Verify the signature on an incoming document

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Encryption

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup (setup.cmd)

  • Obtain and Install Digital Certificates

  • Create Secure Ports and Channels

  • Create File Receive Functions

  • Run the Sample Scenario

Programming Notes

The sample scenario simulates establishing secure communications between two organizations: Buyer and Home. These organizations can be considered as separate Web sites.

A flat-file purchase order, myPO.csv, is sent from Buyer to Home. Because the purchase order is considered sensitive, the information needs to be encrypted and signed by Buyer before it is transported. Encryption prevents documents from being viewed by unauthorized individuals. Signing ensures that a document is authentic and unaltered. Home decrypts, verifies, and transforms the purchase order as an XML document of decision factors.

This sample requires obtaining certificates for each organization to perform the encryption, decryption, and digital signature. It is recommended that you familiarize yourself with certificates before using this sample.


Preliminary Setup (setup.cmd)

Running setup.cmd in the sample directory performs the following tasks, which are described in detail in the following topics:

  • Create Folders

  • Create Organizations

  • Create Document Definitions

  • Set Up Map

  • Create Envelope

If you encounter errors, be sure to clear out all conflicting organizations, document definitions, and so on that are used in this scenario before running setup.cmd.


Create Folders

In this procedure, you create one folder that contains three subfolders. Each subfolder simulates an organization in the scenario.

To create the folders:

  1. In Windows Explorer, browse to the root directory of your C drive.

  2. Create a new folder on the root of the C drive; name the folder Encryption.

  3. Click the new Encryption folder and create three subfolders with the following names:
    • Buyer

    • Home

    • Approver


Create Organizations

In this procedure, you will create the three organizations in the scenario.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Messaging Manager.

  2. If the BizTalk Messaging Manager dialog box appears, click Cancel.

  3. In the left frame, click Organizations, and then click Search Now.

  4. Right-click the organization view window and click New Organization on the context menu.

  5. Type Buyer in the Organization name box and click OK.

  6. Repeat steps 4 and 5 for the Home and Approver organizations.


Create Document Definitions

In this procedure, you will examine and store three document specifications to WebDAV and create three document definitions that are based on the following specifications:

  • BasicPO. The purchase order sent by Buyer for approval.

  • DecisionFactors. The decision factors extracted from the basic purchase order that are relevant for approval.

  • Response. The final approval response: yes or no.

  • To create the document definitions:
  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Editor.

  2. For each of the following document specifications, on the File menu, click Store to WebDAV, and store these document specifications in the same folder:

    defBasicPO.xml

    defDecisionFactors.xml

  3. In the left frame of BizTalk Messaging Manager, click Document definitions, and then click Search Now.

  4. Right-click in the right frame and click New Document Definition on the context menu.

  5. Type BasicPO in the Document definition name box.

  6. Select the Document specification check box and click Browse.

  7. Select defBasicPO.xml in the WebDAV repository and click Open.

  8. Click OK to close the New Document Definition dialog box.

  9. Repeat steps 4-8 for the document specification defDecisionFactors.xml, naming it DecisionFactors.


Set Up Map

The file mapBasicPO_DecisionFactors.xml specifies how the BasicPO source specification should be converted to the DecisionFactors destination specification. Review and compile the map, and store it to WebDAV for future use.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Mapper.

  2. On the File menu, click Open, or use the toolbar icon to navigate to and select mapBasicPO_DecisionFactors.xml.

  3. On the Tools menu, click Compile Map, or press F5, or click the toolbar icon that is second from the right.

  4. On the File menu, click Store to WebDAV, and place the map into the BizTalk Server repository under the name mapBasicPO_DecisionFactors.xml.


Create Envelope

In this procedure you will create the BasicPOEnv envelope that is used to wrap the flat-file purchase order that is sent from Buyer. Envelopes are needed whenever you are using non-XML documents.

  1. In the left frame of BizTalk Messaging Manager, click Envelopes and then click Search Now.

  2. Right-click in the right frame and click New Envelope on the context menu.

  3. Type BasicPOEnv in the Name text box.

  4. Select FLATFILE from the Envelope Format drop-down list.

  5. Select the Envelope specification check box and click Browse.

  6. Click defBasicPO.xml in the WebDAV repository and click Open.

  7. Click OK to close the New Envelope dialog box.


Obtain and Install Digital Certificates

This sample requires the use of two certificates. These certificates must either be obtained from a trusted certification authority (CA), or be created by using Microsoft Certificate Services. One certificate will be denoted as the Buyer certificate, and the other as the Home certificate. A purchase order will be encrypted and signed, and then decrypted and verified with these two certificates.

To create the certificates by using Microsoft Certificate Services, follow these guidelines. Note that these guidelines are subject to change. For more information about creating certificates, see the Certificate Services Help file that is available in the Certification Authority MMC snap-in.

  • Install Certificate Services

  • Request Certificates

  • Issue Certificates

  • Install MMC Certificates Snap-in

  • Install Certificates to Personal Store

  • Install Certificates to BizTalk Store


Install Certificate Services

  1. On the Start menu, point to Settings, and then click Control Panel.

  2. Double-click Add/Remove Programs.

  3. Click Add/Remove Windows Components, click Certificate Services, and then click Next.

  4. Complete the steps in the Certificate Services installation wizard.

    For this sample, it is sufficient to use the wizard's default selected options.


Request Certificates

  1. Use your browser to navigate to http://localhost/certsrv/default.asp.

  2. Click Request a certificate and then click Next.

  3. Select Advanced request and then click Next.

  4. Select Submit a certificate request to this CA using a form and then click Next.

  5. Under Identifying Information, enter Buyer as the Name.

    Enter other identifying information as desired.

  6. Under Key Options, select Mark keys as exportable and Use local machine store.

    Keeping these options selected ensures that the certificate gets installed on the local computer and can be exported to a file.

  7. Click Submit.

  8. Repeat steps 2 through 7, changing the certificate name to Home.


Issue Certificates

  1. On the Start menu, point to Settings, and then click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Certification Authority.

  4. Fully expand the Certificate Authority tree and click the Pending Requests folder.

    Two new requests for certificates should appear.

  5. Select both new pending requests and right-click.

  6. Click All Tasks, and then click Issue.

    The requests should now disappear from the Pending Requests folder.

  7. Verify that the certificates now appear in the Issued Certificates folder.


Install MMC Certificates Snap-in

BizTalk Server uses the Local Computer certificate store to locate digital certificates. Install the MMC Certificates snap-in to be able to manage the certificates.

  1. On the Start menu, click Run, and then type mmc to start Microsoft Management Console.

  2. On the Console menu, click Add/Remove Snap-in.

    The Add/Remove Snap-in dialog box is displayed.

  3. Click Add and select Certificates.

  4. Select Computer account as the account for which the snap-in will manage certificates.

  5. Click Next to go to the Select Computer dialog box.

  6. The default Local computer should be selected. Click Finish.

  7. Click Close to close the Add Standalone Snap-in dialog box.

  8. Click OK to close the Add/Remove Snap-in dialog box.

  9. Keep the Console window open to verify installation in future steps.


Install Certificates to Personal Store

  1. Use your browser to navigate to http://localhost/certsrv/default.asp.

  2. Click Check on a pending certificate and then click Next.

  3. Click the first certificate request and then click Next.

  4. Click Install this certificate.

  5. Open the Microsoft Management Console window with the Certificates snap-in installed.

  6. Navigate to Certificates (Local Computer) | Personal | Certificates in the left frame.

  7. Verify that a new certificate with the name specified (for example, Buyer) has been installed.

  8. Repeat steps 2 through 7 to install the remaining certificate request.


Install Certificates to BizTalk Store

  1. In the Console window, right-click the Buyer certificate, and select All Tasks | Export.

    The Certificate Export Wizard appears.

  2. Click Next.

  3. In the Export Private Key dialog box, select No, do not export the private key, and then click Next.

    The BizTalk Server store does not require certificates with private keys.

  4. Click Next to get to the File to Export dialog box.

  5. Click Browse and enter a file name for the exported certificate (for example. c:\Encryption\buyer.cer).

    Remember the certificate location and file name for future steps.

  6. Click Next and then click Finish.

    A dialog should appear indicating that the export was successful.

  7. Repeat the preceding steps to export the Home certificate.

  8. In the left frame of the Console, right-click the BizTalk folder under Certificates (Local Computer).

  9. Click All Tasks, and then click Import.

    The Certificate Import Wizard appears.

  10. Click Next.

  11. Click Browse to navigate to and select the Buyer certificate.

  12. Click Next, click Next again, and then click Finish.

    A dialog should appear indicating that the import was successful.

  13. Repeat the preceding steps to import the Home certificate.

  14. Navigate to Certificates (Local Computer) | BizTalk | Certificates to verify that the two certificates have been imported.


Create Secure Ports and Channels

This section shows how to create ports and channels that carry out encryption, decryption, signing, and verification. Two ports and two channels will be created.

This section contains the following topics:

  • Create Port and Channel to Encrypt and Sign Outbound Files

  • Create Port and Channel to Receive Encrypted and Signed Files


Create Port and Channel to Encrypt and Sign Outbound Files

In this section, you will create the port BuyerEncryptPort and the associated channel BuyerEncryptChannel to encrypt and sign documents. Because the documents are sent from Buyer to Home, they need to be encrypted with Home's public key and signed with Buyer's private key. The certificates used for signing and encryption will be specified in the properties of both the port and the channel.

  1. In Biztalk Messaging Manager, on the File menu, click New, click Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. In the Name box, type BuyerEncryptPort and then click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

  4. Select Buyer from the list of available organizations, and then click Next.

  5. In the Primary Transport box, click Browse, and choose File as the Transport Type.

  6. Type (after file://) c:\Encryption\Buyer\Encrypted\myPO_%tracking_id%.txt as the file name.

    The use of %tracking_id% allows each document to be saved to a unique file name.

  7. Click OK to close the Primary Transport dialog box.

  8. Click Next twice to get to the Security Information page.

  9. In the Encryption group box, select S/MIME from the Type drop-down list and click Browse.

    A list appears, showing certificates that are stored on the computer with public keys.

  10. Select the Home digital certificate and click OK.

  11. In the Signature group box, select S/MIME from the Type drop-down list.

    The digital certificate used to sign the document will be specified in the channel.

  12. Verify that the Create a channel for the messaging port check box is selected.

  13. Select "From an organization" as the Channel Type and click Finish.

    The New Channel Wizard opens.

  14. On the General Information page, in the Name box, type BuyerEncryptChannel and click Next.

  15. On the Source Organization page, in the Organization area, click Browse.

  16. Select Buyer from the list of available organizations, and then click Next.

  17. On the Inbound Document page, click Browse and select BasicPO as the document definition.

  18. Click Next.

  19. On the Outbound Document page, click Browse and again select BasicPO as the document definition.

  20. Select "Sign outbound document" and click Browse.

    A list appears, showing certificates that are stored on the computer with private keys.

  21. Select the Buyer digital certificate and click OK.

  22. Click Next twice, and then click Finish.


Create Port and Channel to Receive Encrypted and Signed Files

In this section, you will create the port SubmitPort and the associated channel BuyerHomeChannel for transporting an encrypted and signed purchase order from the Buyer to the Home organization. The flat-file purchase order has been signed with Buyer's private key and encrypted with Home's public key. Therefore, it needs to be verified with Buyer's public key and decrypted with Home's private key. The certificates that are used for verification and decryption will be specified in the properties of BuyerHomeChannel.

  1. In BizTalk Messaging Manager, on the File menu, click New, click Messaging Port, and then click To an Organization.

    The New Messaging Port Wizard opens.

  2. In the Name box, type SubmitPort and click Next.

  3. On the Destination Organization page, in the Organization area, click Browse.

  4. Select Home from the list of available organizations, and then click Next.

  5. In the Primary Transport box, click Browse, and choose File as the Transport Type.

  6. Type (after file://) c:\Encryption\Home\DecisionFactor_%tracking_id%.xml as the file name.

    The use of %tracking_id% allows each document to be saved to a unique file name.

  7. Click OK to close the Primary Transport dialog box.

  8. Click Next twice.

  9. On the Security Information page, verify that the Create a channel for the messaging port check box is selected.

  10. Select "From an organization" as the Channel Type, and click Finish.

    The New Channel Wizard opens.

  11. On the General Information page, in the Name box, type BuyerHomeChannel and click Next.

  12. On the Source Organization page, in the Organization area, click Browse.

  13. Select Buyer from the list of available organizations, and then click Next.

  14. On the Inbound Document page, click Browse and select BasicPO as the document definition.

  15. Select Verify decryption on inbound document, and click Browse.

    A list appears, showing certificates that are stored on the computer with private keys.

  16. Select the Home digital certificate and click OK.

    Because Home's public key was used to encrypt the purchase order, Home's private key must be used to decrypt it.

  17. Select Verify signature on inbound document, and click Browse.

    A list appears, showing certificates that are stored on the computer with public keys.

  18. Select the Buyer digital certificate and click OK.

    Because Buyer's private key was used to sign the purchase order, Buyer's public key must be used to verify the signature.

  19. Click Next.

  20. On the Outbound Document page, click Browse and select DecisionFactors as the document definition.

  21. Make sure that "Map inbound document to outbound document" is selected.

  22. Click Browse in the Map reference area and select mapBasicPO_decisionfactors.xml.

  23. Click Next twice, and then click Finish.


Create File Receive Functions

This section will create two File receive functions, BuyerReceiveFunction and BuyerEncryptedReceiveFunction, for picking up documents in c:\Buyer and c:\Buyer\Encrypted, respectively.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and then click BizTalk Server Administration.

  2. Expand the Microsoft BizTalk Server 2002 item in the left frame tree until the Queues and Receive Functions nodes are fully expanded.

  3. Add a new File receive function either by clicking the Receive Functions node and choosing Action | New | File Receive Function from the menu bar or by right-clicking the Receive Functions node and choosing New | File Receive Function from the context menu.

  4. Type BuyerReceiveFunction in the Name box. Comments can be left blank. The computer you are working on should be pre-selected in the drop-down list titled Server on which.

  5. Type myPO.csv in the text box labeled File type to poll for.

  6. Type c:\Encryption\Buyer in the text box labeled Polling Location.

  7. Click Advanced.

  8. In the Envelope Name drop-down list, select BasicPOEnv.

  9. In the Channel Name drop-down list, select BuyerEncryptChannel.

  10. Click OK to close the Advanced dialog box, and OK to close the Add a File Receive Function dialog box.

  11. Add the second File receive function with the name BuyerEncryptReceiveFunction.

  12. Type myPO*.txt in the text box labeled File type to poll for.

  13. Type c:\Encryption\Buyer\Encrypted in the text box labeled Polling Location.

  14. Click Advanced.

  15. In the Envelope Name drop-down list, select BasicPOEnv.

  16. In the Channel Name drop-down list, select BuyerHomeChannel.

  17. Click OK to close the Advanced dialog box, and OK to close the Add a File Receive Function dialog box.


Run the Sample Scenario

To run the sample, put the comma-delimited purchase order myPO.csv into the c:\Encryption\Buyer folder. This file gets signed and encrypted, and finally is transformed as a decision factor output to the c:\Encryption\Home folder.

This section contains the following topics:

  • Disable Intermediate Receive Function

  • Encrypt and Sign an Outbound Document

  • Receive an Encrypted and Signed Purchase Order


Disable Intermediate Receive Function

Temporarily disabling the receive function BuyerEncryptReceiveFunction will allow the intermediate signed and encrypted purchase order to be viewed.

  1. In the left frame of BizTalk Server Administrator, expand the tree down to the level of the Receive Function nodes.

  2. Right-click the receive function BuyerEncryptReceiveFunction and click Properties.

  3. Select the Disable receive function check box on the General tab.

  4. Click Yes to confirm.

  5. Click OK to close the receive function properties.


Encrypt and Sign an Outbound Document

  1. With BizTalk Server running, navigate to c:\Encryption\ and copy the file myPO.csv into c:\Encryption\Buyer.

    This file should be consumed by BizTalk Server, transformed, and submitted to c:\Encryption\Buyer\Encrypted as the file myPO_%tracking_id%.txt, where %tracking_id% is a unique ID value.

  2. Open c:\Encryption\Buyer\Encrypted\myPO_%tracking_id%.txt in Notepad to see that the content has been encrypted and signed.

  3. Close c:\Encryption\Buyer\Encrypted\myPO_%tracking_id%.txt.


Receive an Encrypted and Signed Purchase Order

  1. Enable the BuyerEncryptReceiveFunction by clearing the Disable receive function check box under the Properties of the receive function.

    The file myPO_%tracking_id%.txt in the c:\Encryption\Buyer\Encrypted folder should be consumed.

  2. Open the c:\Encryption\Home folder and look for a file called decisionfactor_%tracking_id%.xml, where the %tracking_id% symbol will be replaced with a GUID value.

  3. Open decisionfactor_%tracking_id%.xml in Notepad or Internet Explorer to verify that the content is valid XML.


Flat-File Delimited

This sample translates an inbound delimited flat-file source document into an XML destination document.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Flat-File Delimited

User's Guide

Before running the sample, complete the following steps:

  1. On the C drive, create a folder called FlatFileDelimited.

  2. On the C drive, create a folder called XMLDest.

  3. Copy FlatFileDelimited.xml to the folder \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft on the installation drive.

  4. Run FlatFileDelimitedSetup.vbs to configure BizTalk Messaging Services.

Note

  • The BizTalk Messaging Services configuration script, FlatFileDelimitedSetup.vbs, should be run only once. If you want to run the script again, you must first delete any configuration objects previously created by the script in the following order:
    1. Channel: Flat File Delimited To XML Channel

    2. Port: Flat File Delimited to XML Port

    3. Organization: Flat File Delimited Sample Org

    4. Document definition: Flat File Delimited to XML

    5. Envelope: Flat File Delimited Envelope

    6. File receive function: FlatFileDelimited

To run the sample, follow these steps:

  1. Ensure that the FlatFileDelimitedSampleData.txt file is not read-only. To modify this property, right-click the file, click Properties, clear the Read-only attribute, and then click OK.

  2. Copy and paste the flat file, FlatFileDelimitedSampleData.txt, to the C:\FlatFileDelimited folder. You should see an output XML file in the C:\XMLDest folder.

Programming Notes

The same document specification, FlatFileDelimited.xml, is used for both the inbound and outbound documents, so a map is not required.

Related Topic

Working with Positional and Delimited Flat Files


Flat-File Positional

This sample translates an inbound positional flat-file source document into an XML destination document.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Flat-FilePositional

User's Guide

Before running the sample, complete the following steps:

  1. On the C drive, create a folder called FlatFilePosSample with two subfolders called SourceOrg and DestOrg.

  2. On the BizTalk Server installation drive, copy FlatFilePosSpec.xml to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

  3. Run FlatFilePosConfig.vbs to configure BizTalk Messaging Services.

To run the sample, follow these steps:

  1. Ensure that the FlatFilePosSampleData.txt file is not read-only. To modify this property, right-click the file, click Properties, clear the Read-only attribute, and then click OK.

  2. Copy and paste the flat file, FlatFilePosSampleData.txt, to the C:\FlatFilePosSample\SourceOrg folder. You should see an output XML file in the C:\CustomCounterSample\DestOrg folder.

Note

  • The BizTalk Messaging Services configuration script, FlatFilePosConfig.vbs, should be run only once. If you want to run the script again, you must first delete any configuration objects previously created by the script in the following order:
    1. Channel: FlatFile Positional Channel

    2. Messaging Port: FlatFile Positional Port

    3. Organizations: FlatFilePos Source Organization, FlatFilePos Destination Organization

    4. Document Definition: FlatFilePosDef

    5. Envelope: FlatFilePosEnv

    6. File Receive Function: FlatFilePos

Programming Notes

The same document specification, FlatFilePosSpec.xml, is used for both the inbound and outbound documents, so a map is not required.

Related Topic

Working with Positional and Delimited Flat Files


HTTP Receive Function

This sample illustrates how an online buyer organization delivers a purchase order (PO) to a supplier organization through a Web-based front end. The information is converted to an XML document and is sent to BizTalk Server by using an HTTP receive function.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\HTTP Receive Function

User's Guide

To prepare and run the sample, follow these steps:

  • Set Up the Web Site Environment

  • Run the HTTP Receive Function Sample

Note

  • This sample assumes that BizTalk Server is installed on your C drive. If this is not the case, you should make the appropriate path modifications.


Set Up the Web Site Environment

This section shows you how to set up the Web-based order entry screen, the IIS virtual directory, and the objects that are needed to create and deliver an XML document by using an HTTP receive function.

This section contains the following topics:

  • Create a Web Application

  • Configure the IIS COM+ Package

  • Examine Default.htm

  • Examine ProcessPO.asp

  • Create an HTTP Receive Function


Create a Web Application

In this procedure, you create a Web application to host the order entry form and send the contents to the HTTP receive function.

  1. On the Start menu, point to Settings, and then click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Internet Services Manager.

    The Internet Services Manager console appears.

  4. In the Internet Services Manager console tree, expand the <your computer> node.

  5. Right-click Default Web Site.

  6. On the Action menu, click New, and then click Virtual Directory.

    The Virtual Directory Creation Wizard appears.

  7. On the Welcome to the Virtual Directory Creation Wizard page, click Next.

  8. On the Virtual Directory Alias page, in the Alias box, type PurchaseSite and then click Next.

  9. On the Web Site Content Directory page, click Browse.

  10. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\SDK\HTTP Receive Function, click OK, and then click Next.

  11. On the Access Permissions page, make sure that the Execute (such as ISAPI applications or CGI) option is selected and then click Next.

  12. Click Finish to close the Virtual Directory Creation Wizard.

  13. Right-click PurchaseSite.

  14. On the menu that appears, click Properties.

  15. In the Virtual Directory section, make sure that Execute Permissions is set to Scripts and Executables.

  16. In the same section, change the Application Protection option to High (Isolated).

  17. Click OK.

  18. Copy the BizTalkHTTPReceive.dll file to the location that was specified on the Web Site Content Directory page during the creation of the virtual directory.


Configure the IIS COM+ Package

In this procedure, you modify the account under which the Internet Information Services component runs for PurchaseSite.

  1. On the Start menu, point to Settings, and then click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Component Services.

  4. In the Component Services Manager console tree, expand the Component Services node.

  5. Expand Computers, and then expand COM+ Applications.

  6. Right-click IIS-{Default Web Site//Root/PurchaseSite}.

  7. Click Properties.

  8. The IIS-{Default Web Site//Root/PurchaseSite} Properties manager appears.

  9. Click the Identity tab.

  10. Change the account under which the application will run to Interactive user – the current logged on user, or to a user with the appropriate authority.


Examine Default.htm

Look at Default.htm. This HTML file is located in the HTTP Receive Function sample folder, and is a Web-based entry form that will post the information entered to the ProcessPO.asp file.


Examine ProcessPO.asp

Look at ProcessPO.asp. This .asp file is located in the HTTP Receive Function sample folder, and accepts the information that Default.htm sends to it. This .asp file takes the information that is entered in the HTTP form, converts the information into well-formed XML, and posts the XML to the PurchaseSiteFunc HTTP receive function.


Create an HTTP Receive Function

In this procedure, you create an HTTP receive function to process the purchase order.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server, expand BizTalk Server Group, and then click Receive Functions.

  3. On the Action menu, point to New, and then click HTTP Receive Function.

    The Add an HTTP Receive Function dialog box appears.

  4. In the Name box, type PurchaseSiteFunc.

  5. In the Server on which the receive function will run box, click the name of a server in the BizTalk Server group.

  6. In the Virtual directory box, type PurchaseSite/biztalkhttpreceive.dll?PO.

  7. In the Submit to drop-down list box, select the File option.

    You can also configure the HTTP receive function to send the data received to BizTalk Server synchronously or asynchronously.

  8. In the File Path and Name box, type \Program Files\Microsoft BizTalk Server\SDK\HTTP Receive Function\PurchaseOrder_%guid%.xml.

    This is the path of the file that the HTTP receive function will create. Notice that the GUID is used as a unique identifier.

  9. Click OK to close the Add a File Receive Function dialog box.

  10. Close BizTalk Server Administration.


Run the HTTP Receive Function Sample

This section shows you how to run the HTTP receive function sample.

  1. Open your Web browser.

  2. Point your browser to the virtual directory that you created earlier (for example, http://localhost/PurchaseSite).

    This will bring up the HTTP Receive Function Sample Purchase Order Form.

  3. Enter information in the various fields and then click Submit.

    This will send the information that you just entered to the ProcessPO.asp file. This .asp file will convert the information into well-formed XML and then post the information to the PurchaseSiteFunc HTTP receive function that you created earlier.

  4. A reply message will be displayed stating that the BizTalk Server system has processed your order.

    You can verify this by looking in the \Program Files\Microsoft BizTalk Server\SDK\HTTP Receive Function directory for an XML file.


Mapping Twice

This sample demonstrates mapping a document from its source to its destination by using two iterations.

Biztalk Server allows you to map a document synchronously through two iterations by using SubmitSync and the Loopback transport service. You can break your mapping into various stages by reusing and combining different channels.

In this scenario, we will first map Input.xml (which is hard-coded in the Microsoft Visual Basic source) to an intermediate XML file by using 1stMap.xml. A message box will report the resulting IntermediateOutput.xml file. Then we will map IntermediateOutput.xml to the final destination, producing FinalOutput.xml.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Mapping Twice

User's Guide

Before running the sample, complete the following steps:

  1. In the Mapping Twice sample directory, double-click the DocSpecs folder.

  2. Copy the Microsoft folder and paste it into the DocSpecs repository at:

    \Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs

  3. In the Mapping Twice sample directory, double-click the Maps folder.

  4. Copy the Microsoft folder and paste it into the Maps Repository at:

    \Microsoft BizTalk Server\BizTalkServerRepository\Maps

  5. Double-click SetUp.vbs to run Setup.

To run the sample:

  • Run Mapping_Twice.exe.

Programming Notes

In the first mapping, the following files are used:

File name | Purpose
Input.xml | Source instance file
SourceDocSpec.xml | Source specification file
IntermediateDocSpec.xml | Intermediate specification file
1stMap.xml | Map source file
IntermediateOutput.xml | Intermediate instance after first mapping

In the second mapping, the following files are used:

File name | Purpose
IntermediateOutput.xml | Intermediate instance file
IntermediateDocSpec.xml | Intermediate specification file
DestinationDocSpec.xml | Destination specification file
2ndMap.xml | Map source file
FinalOutput.xml | Final instance after first mapping

When running the sample, the first Msgbox should correspond to /Data/IntermediateOutput.xml, and the second Msgbox should correspond to /Data/FinalOutput.xml.

The application will create two files in the Mapping Twice sample folder: SampleIntermediateOutput.xml and SampleFinalOutput.xml. These files hold the values in the two messages that are displayed when you run the Mapping_Twice.exe file.

The BizTalk Messaging Services configuration script, SetUp.vbs, should be run only once. If you want to run the script again, you must first delete the configuration objects, such as organizations, ports, channels, and so on, that were previously created by the script.


Message Queuing 4 MB Limit

This sample shows one way to process documents that exceed the Message Queuing maximum size limit. Depending on your requirements, this method might not be suitable.

Message Queuing is limited in the size of documents that can be processed. The maximum size document that Message Queuing supports is 4 MB if the document is in ASCII. The message queue can handle a maximum of 2 MB if the document is in Unicode.

In the Message Queuing 4 MB sample, a buyer organization delivers a large purchase order (PO) file, in excess of 4 MB, to a supplier organization by using the BizTalk Framework 2.0 reliable messaging protocol.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\MSMQ 4MB Limit

User's Guide

Before running the sample, complete the following steps:

  1. In the MSMQ 4MB Limit directory remove the read-only property on the following files:

    BigCustomerPO.xml

    CustomerPO.xml

    MSMQ 4MB Limit.skv

    MSMQ 4MB Limit.skx

  2. Copy the following files to the Biztalk Repository at \Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft:

    \Setup\Docs\customerid.xml

    \Setup\Docs\largeFileReceive.xml

  3. Create a private transactional queue named customeridq in the Computer Management tool. Be sure to modify the security settings for this queue to allow everyone full control.

  4. In the SetUp folder, run SetUp.cmd and follow the prompts.

  5. Close the Command window if it is still open.

  6. Install XML for SQL Server Web Release 1 (WR1) by finding the downloadable release at: www.microsoft.com/sql/downloads.

  7. Modify the CustomerPO.xml and BigCustomerPO.xml files so that they are editable. By default, the files are read-only. If the file attributes are not changed, the sample will not work correctly.

    XML for SQL Server is required for this sample.

Verify that the settings are correct:

  1. Open Biztalk Server Administration. Expand the Console Root until you see Receive Functions.

  2. Click filercv_CustomerPO. In the right pane, edit this File receive function by double-clicking filercv_CustomerPO.

  3. On the General tab, be sure that the Disable Receive Function check box is cleared.

  4. On the Services tab, be sure that the Polling Location is polling in the \POdrop folder in your Samples directory.

  5. Click OK.

  6. Click msmqrcv_CustomerID. In the right pane, edit this File receive function by double-clicking msmqrcv_CustomerID.

  7. On the General tab, be sure that the Disable Receive Function check box is cleared.

Modify the Orchestration schedule:

  1. Edit the Orchestration schedule by right-clicking MSMQ 4MB Limit.skv and selecting Edit With Orchestration Designer.

  2. Double-click the blue line connecting the port to the action "Receive CustomerID from Queue."

  3. Click Next four times until you see Message Specification Information.

  4. Click Browse and select the location of \Schemas\CustomerID.xml in the MSMQ 4MB Limit sample folder.

  5. Double-click the GetSQLData COM shape; this should open the COM Component Binding Wizard.

  6. Click Next twice.

  7. Under Class Information, double-click the GetSqlData folder to expand the component.

  8. Double-click the getData class.

  9. Click Finish.

    If a message box appears, click OK and perform the following steps:

    1. Double-click the red and blue lines connecting the port to the action "Call COM Object."

    2. Click Next.

    3. Click Finish.

    4. Click Yes in the dialog box.

    5. Open the Data Flow page by clicking the Data tab.

    6. Under the msg_CustomerID table, connect CustomerID to the strCust_ID in the getData_in table.

    7. Make the XLANG schedule by clicking Make XLANG MSMQ 4MB Limit.skx on the File menu.

    8. Be sure that XLANG MSMQ 4MB Limit.skx is being created in the MSMQ 4MB Limit samples directory.

    9. Click OK to replace the file.

Update the messaging port

  1. Open Biztalk Messaging Manager and search for all ports.

  2. Double-click the port_CustomerID port.

  3. Click Next.

  4. In the first input box under "New XLANG schedule" click Browse.

  5. Select MSMQ 4MB Limit.skx in your Samples directory.

  6. Click Finish.

To run the sample:

  • Copy CustomerPO.xml and paste it into \PODrop to run this sample. You should see a message box pop up momentarily. Check the Event Logs for errors. The CustomerPO.xml file is a small test file that will be processed in the same manner as a large file. To test a large file, copy the BigCustomerPO.xml file to the \PODrop directory. Processing a large file will take longer.

Programming Notes

The BizTalk Messaging Services configuration script, SetUp.cmd, should be run only once. If you want to run the script again, you must first delete the configuration objects, such as organizations, ports, channels, and so on, that were previously created by the script.

The following objects are created by the setup file:

Organizations

org_CustomerID

org_CustomerPO

Channels

channel_CustomerID

channel_CustomerPO

Document Definitions

docdef_CustomerID

docdef_CustomerPO

Messaging Ports

port_CustomerID

port_CustomerPO

Receive Functions (in BizTalk Server Administration):

filercv_CustomerPO

msmqrcv_CustomerID

Messaging Queues (in Computer Management)

customeridq

BizTalk Server Repository

largeFileReceive.xml

customerid.xml


Multi-Part MIME Attachment

This sample shows how BizTalk Server handles an inbound document that contains multiple MIME attachments.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Multi-Part MIME Attachment

User's Guide

Before running the sample, complete the following steps:

  1. On the Start menu, click Run.

  2. On the command line type CMD.

    This will bring up a Command Line window.

  3. Change the directory to the Multi-Part MIME Attachment sample directory.

  4. Type Config.wsf.

    This will create the MimeSampleSource->MimeSampleDest port, MimeSampleSource->MimeSampleDest channel, CommonPO document definition, BTFEnvelope envelope, and the MimeSample_DestinationOrg and MimeSample_SourceOrg organizations.

  5. Type Exit in the Command Line window to close it.

  6. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Administration.

  7. Double-click Microsoft BizTalk Server 2002.

  8. Right-click BizTalk Server Group, click Properties, and then click the Tracking tab.

  9. Ensure that the Enable Document Tracking and Log the original MIME-encoded message check boxes are selected.

    These options instruct BizTalk Server to store in a table all incoming documents as well as the original MIME documents.

  10. Click OK.

  11. Close BizTalk Server Administration.

To run the sample, follow these steps:

  1. On the Start menu, click Run.

  2. On the command line type CMD.

    This will bring up a Command Line window.

  3. Change the directory to the Multi-Part MIME Attachment sample directory.

  4. Type Submit.vbs.

    This script file will use the Submit method to submit the CommonPOAttached.txt file to BizTalk Server. When the submission process is complete, a message box will appear stating that the submission was successful.

  5. Verify that a new file has been created in the Multi-Part MIME Attachment sample directory. This file will be named with a unique GUID and have a .txt extension (for example, {4DE29CC8-7631-46A7-BCA7-F92B910A2AD1}.txt).

  6. Type Exit in the Command Line window to close it.

    You can verify that the MIME attachments have been included by opening the .txt file. Note that the XML data within the multi-part MIME file is encapsulated by a SOAP envelope.

Programming Notes

This sample assumes that BizTalk Server is installed on your C drive. If this is not the case, you should make the appropriate path modifications.


Pipeline Component in Visual Basic

This sample demonstrates an application integration component (AIC) that implements the IPipelineComponent and IPipelineComponentAdmin interfaces in Microsoft Visual Basic. The component provided in this sample receives a document that validates against the CommonPO.xml schema (provided by default in the Microsoft BizTalk Server repository), logs some of the properties passed to it in the dictionary, and copies the incoming message to a file.

For a related sample, see Pipeline Component in Visual C++.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\PipelineComponent\VB

User's Guide

Before running the sample, complete the following steps:

  1. Compile the Visual Basic component (this is optional because the DLL is provided).

  2. Register the component, its category IDs, and its setup configuration by running:

    cscript scenario.wsf //job:setup

    When asked whether to register information from Affinity.reg, click "Yes." The component ProgID is "BTSSamples_VBPipeComp.PipelineComp".

To run the sample:

  • Submit a document on the channel "BTSSamples_Channel_VBPipeComp" by using the command:

    cscript scenario.wsf //job:submit

    If the submission succeeds, a log file, BTSSamples.log, and an output file, BTSSamples_pipe.out, will be created in the temporary system directory (C:\WINNT\temp).

Programming Notes

If you want to configure the component, you must' copy the ASP pages to the directory designated for property pages (for example, C:\Program Files\Microsoft BizTalk Server\MessagingManager\pipeline). You can then open the BizTalk Messaging Manager and edit the channel. The Advanced button in the last dialog box allows you to set the properties for the primary transport.


Pipeline Component in Visual C++

This sample demonstrates an application integration component (AIC) that implements the IPipelineComponent and IPipelineComponentAdmin interfaces by using the Active Template Library (ATL). The component provided in this sample receives a document that validates against the CommonPO.xml schema (provided by default in the Microsoft BizTalk Server repository), logs some of the default dictionary properties to a file, C:\temp\BTSSamples_ATLPipeComp.log, and writes the incoming data to another file, C:\BTSSamples_ATLPipeComp.out.

For a related sample, see Pipeline Component in Visual Basic.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\PipelineComponent\VC\ATL

User's Guide

Before running the sample, complete the following steps:

  1. Compile the Visual C++ component.

  2. Set up the configuration by running:

    cscript scenario.wsf //job:setup

    The component ProgID is "BTSSamples_AtlPipelineComp BTSPipelineComp".

  3. Copy ASP files to the configuration files for BizTalk Messaging Manager:

    C:\Program Files\Microsoft BizTalk Server\MessagingManager\pipeline

    You can now change the default settings for output and log files.

To run the sample:

  • Submit a document on the channel "BTSSamples_Channel_ATLPipelineComp" by using the command:

    cscript scenario.wsf //job:Submit

    If the submit succeeds, you will get two files:

    C:\temp\BTSSamples_ATLPipeComp.log

    C:\temp\BTSSamples_ATLPipeComp.out


Queue Sniffer

This sample enables you to view, forward, and remove messages in Message Queuing queues. This application supports the following features:

  • Displays the entire content of a message

  • Displays XML and flat text file formats

  • Accesses message queues on remote servers

  • Performs criteria-based searches for specific messages

  • Forwards messages to other message queues

  • Removes messages from a queue

  • Retrieves detailed message information

  • Displays journal messages

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Queue Sniffer

User's Guide

To use this application, perform the following steps:

  1. Run the executable file QueueSniffer.exe, located on the BizTalk Server installation drive at \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Queue Sniffer\QueueSniffer.exe.

  2. Type the name or TCP/IP address of a Message Queuing server in the Message Queuing Server text box that is located at the top of the window.

  3. Type a message queue name in the Message Queue text box.

  4. If the queue you are accessing is transactional, select the Use Transactional Queue check box.

  5. If you wish to view journal messages for the queue, select the Use Journal check box.

After you have entered the required information, you can perform one of the following actions:

  • View the next message in the queue. Click View Next Message to display the next message in the queue.

  • Search for a specific message in the queue. Enter search criteria in the Message Search Criteria section and click Search to display a message that matches your criteria. Click Search again to see the next message that matches your search criteria.

After a message is displayed in the Message Information area, you can remove the message from the queue by clicking Remove from Queue, or you can forward a copy of the message to another queue by clicking Forward Message.

Note

  • The information in the message label cannot be passed to a remote queue.


Receive Scripts

This sample demonstrates an HTTP receive function.

ReceiveResponse.asp is used as a page where the BizTalk Messaging Service receives documents to be sent to an existing Orchestration schedule. If you copy that page into your localhost location, you can use http://localhost/ReceiveResponse.asp as the HTTP URL address on the Channel Information page of the BizTalk Messaging Binding Wizard.

ReceiveStandard.asp is an example of an HTTP receive function. The document data posted to that page will be submitted as a self–routing document for a NOT OPEN configuration.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReceiveScripts

Programming Notes

The Exchange Server 5.5 folder contains an example SMTP receive function. The document data sent as an e-mail message will be deposited into C:\temp\RS_data.txt and then submitted as a self-routing document for a NOT OPEN configuration.

The Exchange Server 2000 folder contains an example of an event sink that intercepts e-mail messages and submits them to BizTalk Server. See the readme.doc file in that folder for more details.


Refresh Messaging Manager

This sample allows you to refresh objects in BizTalk Messaging Manager. You must refresh the objects in the Messaging Manager when a document definition, envelope, or channel is modified. This sample lets you choose whether to refresh all objects or individual objects.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Refresh Messaging Manager

User's Guide

To prepare and run the sample, follow these steps:

  1. Copy the BTM_RefreshV2.exe file to the BizTalk Server on which you are working.

    The BTM_RefreshV2.exe file can be copied to any BizTalk Server. The Refresh Messaging Manager application will only affect the BizTalk Server that it is currently running on.

  2. Open Windows Explorer and browse to the BTM_RefreshV2.exe file.

  3. Double-click the BTM_RefreshV2.exe file to start the application.

    Within the application are three windows that display the document definitions, envelopes, and channels that are available on the BizTalk Server.

  4. To refresh individual objects, highlight the objects and then click the corresponding button to refresh only the highlighted objects. To refresh all the listed objects (whether highlighted or not), click Update All.

  5. To exit, click Exit.

Note

  • This sample assumes that BizTalk Server is installed on your C drive. If this is not the case, you should make the appropriate path modifications.


Reliable Messaging

This sample illustrates how a buyer organization delivers a purchase order (PO) to a supplier organization by using the BizTalk Framework 2.0 reliable messaging protocol.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReliableMessaging

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup

  • Enable Reliable Messaging

  • Run the Reliable Messaging Sample

Note

  • The BizTalk Messaging Services configuration script, ReliableMsgConfig.vbs, should be run only once. If you want to run the script again, you must first delete any configuration objects previously created by the script in the following order:
    1. Applications: PurchaserOrgApp, SupplierOrgApp

    2. Channels: PurchaserOrgOutgoingMsgChannel, SupplierOrgIncomingMsgChannel

    3. Messaging Ports: PurchaserOrgOutgoingPort, SupplierOrgIncomingPort

    4. Organization: Supplier Organization

    5. Document Definition: PurchaserOrgPO

    6. Envelope: PurchaserReliableEnvelope

    7. File Receive Functions: PurchaserOrgOutgoingFunc, SupplierOrgIncomingFunc

Programming Notes

BizTalk Framework 2.0 (BTF) guarantees only a single delivery of a message to the destination organization. After the supplier organization receives the message, the BizTalk Server in the supplier organization responds with a receipt to the purchaser organization. When the purchaser organization receives the receipt, the transmission is complete.

As a brief example, consider an application (PurchaserOrgApp) in the buyer organization, which sends a PO to BizTalk Server (PurchaserOrg), which, in turn, delivers the PO to the supplier organization application (SupplierOrgApp), as explained below:

BizTalk Server in the buyer organization

  1. BizTalk Server wraps the PO with a BTF reliable message envelope and sends the message to the supplier organization.

  2. BizTalk Server places a copy of the PO into the BizTalk Server Retry queue.

  3. BizTalk Server tries to send the PO to a supplier organization until a BTF receipt is received. The number of retries is based on the configuration and the interval between retries.

  4. When the number of retries is exhausted and the receipt has not been received, the PO is placed into the Suspended queue.

  5. If the receipt arrives before the number of retries is exhausted, BTF removes the PO from the Retry queue.

BizTalk Server in the supplier organization

  1. BizTalk Server removes the PO from the BTF envelope and sends an acknowledgement receipt to the source organization.

  2. The PO, without an envelope, is delivered to the supplier organization's internal application.

  3. BizTalk Server logs the PO in the document-tracking database. However, no log is created for the receipt.

When BizTalk Messaging Services on the supplier organization receives an interchange with a reliable messaging format, it uses a special document definition, channel, and messaging port to process and transport a receipt to the buyer organization. These special system objects are not viewable in BizTalk Messaging Manager, and you cannot create similar objects by using the reserved system names.

BizTalk Server uses the reply-to address that is included in the header of the inbound interchange as the destination address for the receipt. You do not need to further configure BizTalk Messaging Services for the supplier system to return a receipt for an interchange sent with the reliable messaging envelope.


Preliminary Setup

Before you begin the sample, you must complete the following tasks:

  • Create Folders

  • Copy Files

  • Run Setup Script


Create Folders

In this procedure, you create one folder that contains six subfolders. You use four of the subfolders as locations for messages as they move into and out of the buyer and seller systems, one as a repository for the reliable receipt and one as a document data folder.

To create the folders:

  1. In Windows Explorer, browse to the root directory of your C drive.

  2. Create a new folder on the root of the C drive; name the folder ReliableMessaging.

  3. Click the new ReliableMessaging folder and create two subfolders with the following names:
    • PurchaserOrg

    • SupplierOrg
  4. Click the new PurchaserOrg folder and create two subfolders with the following names:
    • InPurchaserOrg

    • ReliableReceipts
  5. Click the new SupplierOrg folder and create two subfolders with the following names:
    • InSupplierOrg

    • OutSupplierOrg


Copy Files

In this procedure, you copy the files that are needed to complete the sample.

  1. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReliableMesssaging and copy POSpec.xml.

  2. Paste the file to \Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

  3. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReliableMesssaging and copy ReliableMsgReceipt.asp.

  4. Paste the file to C:\ReliableMesssaging\PurchaserOrg.


Run Setup Script

In this procedure, you run the script that sets up all the messaging configuration objects that are necessary for this sample.

  • Run ReliableMsgConfig.vbs to configure BizTalk Messaging Services.


Enable Reliable Messaging

This section shows you how to enable reliable messaging for the sample. It contains the following topics:

  • Create a Web Application

  • Examine ReliableMsgReceipt.asp

  • Define a Reliable Messaging Reply-to URL


Create a Web Application

In this procedure, you create a Web application to receive the reliable messaging receipt.

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Internet Services Manager.

    The Internet Services Manager console appears.

  4. In the Internet Services Manager console tree, expand <your computer>.

  5. Right-click Default Web Site.

  6. On the Action menu, select New and click Virtual Directory.

    The Virtual Directory Creation Wizard appears.

  7. On the Welcome to the Virtual Directory Creation Wizard page, click Next.

  8. On the Virtual Directory Alias page, in the Alias box, type PurchaserOrg and click Next.

  9. On the Web Site Content Directory page, click Browse.

  10. Browse to C:\ReliableMessaging\PurchaserOrg, click OK, and then click Next.

  11. On the Access Permissions page, click Next.

  12. Click Finish to close the Virtual Directory Creation Wizard.


Examine ReliableMsgReceipt.asp

Look at ReliableMsgReceipt.asp. This ASP file is located in the PurchaserOrg directory, and is a standard receive page that delivers the receipt to the buyer organization, using BizTalk Framework 2.0.

For the call to Submit, the only parameters specified are the openness type and the document string, as shown in the following code:

SubmissionHandle = interchange.submit( 1, PostedDocument )

BizTalk Server understands the schema of the reliable message receipt, so you do not need to define a port or a channel to process the receipt.


Define a Reliable Messaging Reply-to URL

In this procedure, you define a reliable messaging reply-to URL.

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Administration.

    The BizTalk Server Administration console appears.

  2. In the BizTalk Server Administration console tree, expand BizTalk Server.

  3. Right-click BizTalk Server Group.

  4. On the Action menu, right-click Properties.

    The BizTalk Server Group Properties dialog box appears.

  5. On the General tab, in the Reliable messaging repy-to URL box, type http://localhost/PurchaserOrg/ReliableMsgReceipt.asp, click Apply, and click OK.

    ReliableMsgReceipt.asp is an ASP file that uses the Submit method to deliver the receipt to the PurchaserOrg BizTalk Server.

    The URL that is specified is used by the supplier system BizTalk Server to deliver the receipt to the buyer system BizTalk Server.


Run the Reliable Messaging Sample

This section shows you how to run the reliable messaging sample. It contains the following topics:

  • Run the Sample with a Disabled Receive Function

  • Run the Sample with an Enabled Receive Function

To run the sample, you need to remove the read-only property from the sample data file, SamplePO.xml.


Run the Sample with a Disabled Receive Function

Run the sample with a disabled receive function to allow you to analyze the content of the inbound purchase order (PO) from the buyer system. You will be able to look at the purchase order wrapped with a BizTalk Framework 2.0 reliable envelope.

Before running the sample, disable the receive function in the seller system, so that you can view the content of the arriving purchase order (PO) from the buyer system. You will be able to analyze the PO wrapped with the BizTalk Framework 2.0 reliable envelope.

To disable the receive function:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server, expand BizTalk Server Group, and then click Receive Functions.

  3. Click the receive function named SupplierOrgIncomingFunc.

  4. On the Action menu, click Properties.

    The Properties dialog box appears.

  5. Select the Disable receive function check box, and then click Yes to confirm your choice.

  6. Click OK.

To submit the PO:

  1. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\ReliableMesssaging and copy SamplePO.xml.

  2. Paste the file to C:\ReliableMesssaging\PurchaserOrg\InPurchaserOrg.

    In this step you place the sample purchase order (PO) to the directory that is being monitored by the buyer system receive function. The receive function will pick up the sample PO.

    At this point, you can view the sample PO in the Retry queue. Note the number of retries and the time interval between each retry.

  3. Browse to C:\ReliableMessaging\SupplierOrg\InSupplierOrg.

    In this directory, you can view the sample PO arriving from the buyer system. The message contains two parts, the SOAP envelope and the body. The body of the message contains the sample PO.


Run the Sample with an Enabled Receive Function

By enabling the receive function on the supplier system, you allow the inbound sample purchase order (PO) to be picked up. Then BizTalk Server removes the envelope, sends a receipt to the buyer system, and submits the PO to the supplier system application through the configured port and channel.

To enable the receive function:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server, and then click BizTalk Server Administration.

  2. Expand Microsoft BizTalk Server, expand BizTalk Server Group, and then click Receive Functions.

  3. Click the receive function named SupplierOrgIncomingFunc.

  4. On the Action menu, click Properties.

    The Properties dialog box appears.

  5. Clear the Disable receive function check box, and then click OK.

    After enabling the receive function, BizTalk Server delivers the reliable message receipt to the reply-to URL, http://localhost/PurchaserOrg/ReliableMsgReceipt.asp.

To complete the sample:

  1. Browse to C:\ReliableMessaging\SupplierOrg\OutSupplierOrg.

    In this directory, you can view the PO. Note that there is no envelope information, and that it is the same PO that was originally sent by the buyer system.

  2. Browse to C:\ReliableMessaging\PurchaserOrg\ReliableReceipts.

    In this directory, you can view the receipt file. The receipt file contains the reply-to URL and the from and to tags. Note that the receipt file contains no information on the PO.


Self-Routing

This sample demonstrates the BizTalk Server 2002 capability to route documents through BizTalk Server channels and ports based on the contents of the document being routed.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Self-Routing

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup

  • Run the Self-Routing Sample

Programming Notes

This sample walks through the process of setting up a self-routing document scheme that utilizes the routing capabilities of BizTalk Server 2002 and, in the process, demonstrates the following:

  • The use of dictionary properties that are added to document specifications by BizTalk Editor and are used by the BizTalk Server runtime to determine routing

  • The use of envelopes to parse and route differently formatted inbound flat files

  • The use of document selection criteria to determine routing

  • The use of receive functions in determining routing

In this sample, we will modify the business scenario and show how a single receive function can be used, with three different inbound file formats, channels, and maps, to send the same DecisionFactors document to the approver through the existing ApprovalMessagingPort port.

We modify the POApproval scenario by introducing the following business requirements:

  • Rather than one buyer organization, as in the original POApproval scenario, we now have two separate buyer departments, each of which has its own flat-file format for a purchase order. The buyer departments are divided by region: Northwest buyers (NWB) and Central buyers (CB).

  • Each buyer department has agreed to add a common header record, known as an inbound envelope, to each of their purchase orders before submitting them for approval. They have also agreed to a data content convention for the common header to properly route their documents.

  • We want to reuse our existing business logic, approver addresses, and wire protocols to route documents from both buyer departments with a minimum of additional effort.

  • We want to use a single share drop location on the network for both departments and a single receive function no matter how many buyer departments we add in the future. Note that we are assuming that all departments added in the future will send flat files with the common header.

Inbound Envelope

Each buyer department uses the inbound envelope to tell BizTalk Server the source of the document and which file format to expect. The envelope has the following format:

POHeader,999,XXX

The first field in the envelope is a constant string literal (that is, identical and unchanging in all documents) that is used to identify the record type when the inbound file is parsed. This is the primary mechanism that BizTalk Server uses at run time to separate individual purchase orders that are submitted in the same flat file.

The second and third fields correspond to the document Source Qualifier and Source Name respectively. In addition, the third field doubles as the Document Type property for the associated purchase order. Because each buyer department sends only one document format, the third field can be "overloaded" in this way.

The Northwest and Central buyer departments provide the Source Qualifier/Source Name pairs 10/NWB and 12/CB, respectively.

A document specification file is provided by the sample and contains the XML-Data Reduced (XDR) information for the envelope. The file name for this specification is defPOEnv.xml. If you look at this file in BizTalk Editor you will see that the string "POHeader" has been entered as the Source Tag Identifier for the record.

Buyer Department Document Specifications and Input Files

The sample provides the document specifications and sample input files for the buyer departments. The specifications are named defNWBPO.xml and defCBPO.xml for the Northwest and Central departments respectively. The sample input files are named NWBPOx.csv and CBPOx.csv, where x is the number of purchase orders in the file (that is, the number of common header records that you should expect to see).


Preliminary Setup

Before you begin the sample, you must complete the following tasks to set up the basic POApproval scenario:

  • Copy Self-Routing Document Specifications and Maps to the Repository

  • Create Two Private Transactional Message Queuing Queues

  • Create Folders

  • Copy Files

  • Remove Read-Only Property from .csv File

  • Run Setup Script

  • Check Receive Function


Copy Self-Routing Document Specifications and Maps to the Repository

  1. In the Self-Routing sample directory, double-click the DocSpecs folder.

  2. Copy the POApproval folder and paste it into the DocSpecs repository at:
    \Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs

  3. In the Self-Routing sample directory, double-click the Maps folder.

  4. Copy the POApproval folder and paste it into the Maps repository at:
    \Microsoft BizTalk Server\BizTalkServerRepository\Maps


Create Two Private Transactional Message Queuing Queues

  1. On the Start menu, point to Settings, click Control Panel, double-click Administrative Tools, and then double-click Computer Management.

  2. Expand the Services and Application node.

  3. Expand the Message Queuing node.

  4. Right-click the Private Queues folder, point to New, and then click Private Queue.

  5. In the Name text box, type approvalmsmq and select the Transactional check box.

  6. Click OK.

  7. Repeat steps 4 through 6 to create another new private queue named responsemsmq.


Create Folders

In this procedure, you create the folder that is necessary to run the sample.

  1. In Windows Explorer, browse to the root directory of your C drive.

  2. Create a new folder on the root of the C drive; name the folder Data.


Copy Files

In this procedure, you copy files that are needed to complete the sample.

  1. On the BizTalk Server installation drive, browse to \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Self-Routing and copy the following two folders: POApproval, SetUp.vbs.

  2. Paste the folders to C:\Data\.


Remove Read-Only Property from .csv File

  1. In the C:\Data\POApproval folder there are three files: NWBPO2.csv, NWBPO1.csv,and CBPO1.csv.

  2. While holding CTRL, select the three files.

  3. Right-click the selection and click Properties.

  4. On the General tab, in the Attributes area, clear the Read-only check box.

  5. Click OK.


Run Setup Script

In this procedure, you run the script that sets up all the ports, channels, document definitions, maps, and specifications that are necessary for this sample.

  1. On the Biztalk Server installation drive, browse to C:\Data and double-click the executable file SetUp.vbs. The command prompt window should appear detailing the configuration process.

  2. When the script finishes, the window should close.


Check Receive Function

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and click Biztalk Server Administration.

  2. From the Console Root navigate to \Microsoft BizTalk Server 2002\BizTalk Server Group\Receive Functions. Right-click ApprovalReceiveFunction and click Properties.

  3. Be sure that the Disable receive function check box is cleared.

  4. Click OK. You can now close Biztalk Server Administration.


Run the Self-Routing Sample

This sample demonstrates that each document is processed through the channel that is designed for that specific document, and that each document is delivered to the Approval queue, ready to be processed by the POApproval.skx schedule. Although the documents have differing sources and starting formats, they are processed by the POApproval scenario with little modification (only the receive function is modified).

This sample also shows how to use BizTalk Document Tracking to check the history and status of documents that pass through BizTalk Server.

This section contains the following topics:

  • Drop Inbound Purchase Orders for Approval

  • Use BizTalk Document Tracking to View Processing History

  • Check That Each Document Is Processed Through the Proper Channel

BizTalk Server needs five key pieces of information to select channels into which to route incoming documents: Source Qualifier, Source Name, Destination Qualifier, Destination Name, and Document Definition Name. Using this data, BizTalk Server queries the BizTalk Messaging Management database to acquire a list of appropriate channels.

An appropriate channel meets all of the following criteria:

  • Its source organization matches the source key values.

  • It is attached to a port with a destination organization that matches the destination key values.

  • It has an inbound document definition name that matches the document definition key name.

The following things happen when one of the self-routing documents is submitted to the receive function:

  • When the receive function loads the document from the monitored file share, it first determines the file type. It does this through a "snoop and loop" approach, testing for each file type in the order specified on the Parsers tab of the Properties dialog for the BizTalk Server Group in the BizTalk Administrator snap-in. In our case, the file is a flat file.

  • All flat files that are consumed by receive functions require an envelope. One of the primary purposes of the envelope is to determine individual document boundaries in the incoming file. Another purpose of the envelope is to act as a reliable way to provide routing information. In our case the source information and the selection criteria for our routing is in the header.

  • To determine the document definition name using the header information, BizTalk Server first uses the document schema (defined in BizTalk Editor and referenced by the document definition in BizTalk Messaging Manager) to parse the header, convert it to XML, and load it into the Document Object Model (DOM). Using the dictionary properties in the header schema, BizTalk Server retrieves three key pieces of information: the source qualifier, the source name, and the document type selection criteria.

  • Because the destination key values are provided to BizTalk Server by the receive function, we have four out of five key values. We still need the document definition to parse and convert the bulk (that is, the non-envelope) portions of the document. BizTalk Server accomplishes this by performing a query against the BizTalk Messaging Management database using the selection criteria, in our case, document_type. For example, BizTalk Server would query for all of the document definitions that have a selection criteria called document_type that is equal to the value pulled from the header, for example, "NWB".

  • After all five keys are determined, BizTalk Server makes the final query to find matching channels. Note that zero or more channels can be returned by this query. For example, finding more than one document with the matching selection criteria could result in more than one channel in the final query. If this happens, the document is submitted to all channels in the query results.


Drop Inbound Purchase Orders for Approval

To exercise the solution that we have now built for self-routing documents, we simply drop one or more of the instance documents provided in the demonstration.

  1. Using Windows Explorer (or other tool of your choice), navigate to c:\data\source and copy the file named NWBPO2.csv and paste it into c:\data\POApproval\PODrop.

  2. After you do this, you should see the VBScript message box that says "PO Approval Submitted for Approval".

  3. If you do not see the message box, then the receive function was unable to use the envelope to parse and route the document to the appropriate channel. Examine the Suspended queue and the Application Event Log for more information.


Use BizTalk Document Tracking to View Processing History

To determine how the documents are actually processed, we can use BizTalk Document Tracking as follows:

  1. On the Start menu, point to Programs, point to Microsoft BizTalk Server 2002, and click BizTalk document tracking on localhost.

  2. In the tracking interface, under Source Selection, select one or both of the organizations that are used in the routing scenario (NWBuyers or CBuyers).

  3. Under Destination Selection, click Home Organization.

    Note that the only document definition that appears in the list is DecisionFactors because that is the only document that is currently configured as an inbound document on any channels that have the source and destination specified.

  4. Under Document Type Selection, click Show Documents.

  5. Click Query.

    Notice that in the Source Selection box, you see only the NWBuyer source. This is because the other sources have not yet sent any documents. Later, , you will see the other source, Cbuyer, appear in the Source Selection box.

  6. In the resulting list, note the key information (source, destination, and document definition name) that defines how the documents were processed. Also notice the time stamp and other information about the documents. Both inbound (native .csv) and outbound (.xml) documents are listed. In addition, you can click the icon in the data column to see the document contents.


Check That Each Document Is Processed Through the Proper Channel

Note that documents with a "2" in the name have two documents contained in the file. Notice that two documents are placed on the Approval queue when these documents are submitted because BizTalk Server breaks up the inbound file based on the flat-file envelope that is used.

  1. Submit each of the files: CBPO1.csv, NWBPO1.csv, and NWBPO2.csv, by dropping each into c:\Data\POApproval\PODrop.

  2. Use BizTalk Document Tracking to review how each document was processed, as described in the preceding topic.


Send to Remote Queue

This sample contains a COM object in the library SendToRemoteQueue.dll that can be used to send XLANG messages to a message queue on a remote server.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Send To Remote Queue

User's Guide

Before running the sample, register the library SendToRemoteQueue.dll on your system by using the RegSvr32 registration utility. This library must be registered on a computer that is running Microsoft BizTalk Server.

This sample provides a simple schedule (RemoteQueue.skv) that reads a common purchase order file (CommonPOSample.xml) from a local message queue, and then sends that purchase order to a remote message queue. To run this schedule, follow these steps:

  1. Create a private queue named .\private$\inbound on the local computer.

  2. Open the file RemoteQueue.skv in BizTalk Orchestration Designer.

  3. Click the Data tab at the bottom of the window.

  4. Double-click the Constants message to open the Constants Message Properties dialog box. Replace the values "RemoteServerName" and "RemoteServerQueue" with the real names of your remote server and queue.

  5. Verify that the QueueType and IsTxn constant values are correct for the remote queue. If not, update them accordingly.

  6. Compile the drawing into an XLANG schedule file (.skx).

  7. Run the XLANG schedule.

  8. Send a message to the .\private$\inbound queue that contains the purchase order data in the file CommonPOSample.xml. Note that the sample does not provide this functionality.

For additional information on compiling and running XLANG schedules, see the following topics:

  • Run XLANG Schedules

  • Compile an XLANG schedule drawing into an XLANG schedule

Programming Notes

To use the sample, add one or more bindings to this COM object in your existing XLANG schedule files. After the object is bound to a schedule, you also need to modify the data mapping in the schedule to specify the remote server and queue name destination for the message. The SendToRemoteQueue object contains the following input parameters for sending messages to a remote queue:

strMessage

String containing the message body.

strMSMQServerName

String containing the name of the remote server computer.

strMSMQQueueName

String containing the name of the remote message queue.

strMSMQQueueType

String containing the type of the remote queue. This value can be set to "PUBLIC" or "PRIVATE".

strMSMQMsgLabel

String containing the label of the message.

bollsQueueTransactional

Boolean that indicates whether the remote queue is transactional.

Note

  • The information in the message label cannot be passed to a remote queue.


Submitting Documents

This sample demonstrates how to set up a BizTalk Messaging Management database and call the Submit method of the Interchange object, which submits a business document to BizTalk Server 2002 from VBScript. The sample also demonstrates the creation and use of an open destination messaging port, organization aliases, custom envelopes, and the IBizTalkTrackData object.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Sample1

User's Guide

Before running the sample, complete the following steps:

  1. Start a Command Line window.

  2. Change the directory to:

    <Microsoft BizTalk Installation Path>\SDK\Messaging Samples\Sample1

To run the sample:

  • Run cscript Sample1.vbs.

Programming Notes

During execution Sample1 outputs messages indicating its progress. It performs the following steps:

  • First it reports the results of using BizTalk Messaging to configure one organization, two documents, one envelope, an open destination port, and a channel.

  • It then reports the results of the Submit method call, waits for 10 seconds, and outputs the content of the tracked business document.

  • Finally, Sample1 creates the file C:\temp\Sample1_<tracking_id_GUID>.txt, which contains a SOAP-enveloped document from the original Sample1.xml data file.

The input file, Sample1.xml, is an XML CommonPO document wrapped in a BizTalk Framework (BTF) 1.0 envelope.

The output file, C:\temp\Sample1_<tracking_id_GUID>.txt, is an XMLCommonPO document identical to Sample1.xml wrapped in a BTF 2.0 envelope, also known as a SOAP envelope.


Submitting Documents with Receipts

This sample shows how to set up a BizTalk Messaging Management database and explains one way of generating a receipt. This is accomplished by mapping a received purchase order (PO) to a PO acknowledgment without using a receipt channel.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Sample2

User's Guide

Before running the sample, complete the following steps:

  1. Start a Command Line window.

  2. Change the directory to

    <Microsoft BizTalk Installation Path>\SDK\Messaging Samples\Sample2

To run the sample:

  • Run cscript Sample2.vbs.

Programming Notes

There are three parties involved in this sample: the source application, the source organization, and the destination organization. The PO originates from the source application, is passed to the source organization, and then is passed from the source organization to the destination organization. The destination organization then sends the PO acknowledgment back to the source organization.

The sample uses local file transport. Two local File receive functions are configured for this sample.Both receive functions call the Submit method of the IInterchange object.

The setup section of the script creates three folders on the C drive. They are C:\temp\SRC, C:\temp\DST, and C:\temp\ACK. This script places the original PO in C:\temp\SRC, and the SRC receive function is configured to pick up files there. The SRC receive function moves the original PO to C:\temp\DST, and the DST receive function places the PO acknowledgment in the C:\temp\ACK folder.

This sample calls SubmitSync for the first submission and overwrites the component configurations on the channel.

The channels created can be described as follows:

SRC/APP->SRC/APP (C:\temp\SRC, used the script to drop a file)

OpenSrc->DST (C:\temp\DST, used receive function to drop a file)

DST->SRC (C:\temp\ACK, used receive function to drop a file)

During execution, Sample2 outputs messages indicating its progress. It performs the following steps:

  • First it copies CommonPOACKMAP.xml into the BizTalkServerRepository\Maps\Microsoft folder.

  • It then verifies the existence of the C:\temp, C:\temp\SRC, C:\temp\DST, and C:\temp\ACK folders, and creates two File receive functions: "SRC File Receive Function" and "DST File Receive Function."

  • The script then tries to remove all pre-existing Sample2-related configuration objects if Sample2 was previously executed. It configures the following Sample2 objects: two organizations, two documents, one envelope, one port, and three channels.

  • It then calls SubmitSync, verifies the response from SubmitSync, waits for one minute, and verifies that no Suspended queue items are present and that the C:\temp\ACK\Sample2ACK.xml file exists. This file should contain CommonPOAcknowledgment wrapped in SOAP envelope.

The input file, Sample2.xml, is an XML CommonPO document wrapped in a BizTalk Framework (BTF) 2.0 (SOAP) envelope.

The output file, C:\temp\ACK\Sample2ACK.xml, is a CommonPOAcknowledgment file mapped from CommonPO and wrapped in a SOAP envelope.


Submitting Documents to a Port Group

This sample sets up a BizTalk Messaging Management database and calls the Submit method of the IInterchange object, which submits the business document to BizTalk Server 2002 synchronously.

A distribution list in BizTalk Server is a way to send an identical business document, containing identical data, to a number of partners. The business document originates from the source application and is passed to the distribution list, which causes the same purchase order (PO) to be sent to the source application and to the destination organization. To verify that the documents have been processed correctly, look for Sample3_DST.txt and Sample3_SRCAPP.txt files in the C:\temp folder.

The sample Distribution List contains related information.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Sample3

User's Guide

To run the sample, follow these steps:

  1. Start a Command Line window.

  2. Change the directory to:

    <Microsoft BizTalk Installation Path>\SDK\Messaging Samples\Sample3

  3. Run cscript Sample3.vbs.

Programming Notes

During execution, Sample3 outputs messages indicating its progress. It performs the following steps:

  • First it copies Sample3.asp into the default Web site of Internet Information Services (IIS).

  • It then tries to remove all Sample3-related Configuration objects if they exist.

  • It configures the following objects: two organizations, one document, one envelope, two ports, one port group, and one channel pointing to the port group (distribution list).

  • It calls Submit, waits for 15 seconds, and verifies that the resulting C:\temp\Sample3_SRCAPP.txt and C:\temp\Sample3_DST.txt files exist.

The C:\temp\Sample3_DST.txt file is created as a result of posting the data to the Sample3.asp page. The C:\temp\Sample3_SRCAPP.txt file is created by a file transport configured in the source application port. The first line of C:\temp\Sample3_DST.txt indicates when the data was received by the destination organization. Both files contain SOAP-enveloped data from the original Sample3.xml.

The input file Sample3.xml is an XML CommonPO document wrapped in a BizTalk Framework (BTF) 2.0 (SOAP) envelope.

The output files are as follows:

  • C:\temp\Sample3_SRCAPP.txt is an XMLCommonPO document identical to the one from Sample3.xml wrapped in a BTF 2.0 envelope, also known as a SOAP envelope.

  • C:\temp\Sample3_DST.txt is an XMLCommonPO document identical to the one from Sample3.xml wrapped in a BTF 2.0 envelope, also known as SOAP envelope, with a first line containing "- Received at date/time -".


Suspended Queue Monitoring

This sample demonstrates how to raise an alert in Microsoft Operations Monitor (MOM) when a document is sent to the BizTalk Server Suspended queue.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Suspended Queue Monitoring

User's Guide

Complete the following steps to configure this sample:

  1. On your C drive, create a folder named ReceivePO.

  2. Run the configuration script, SuspendedQueueConfig.vbs, to configure BizTalk Messaging Services.

  3. Enable the event processing rule named "Suspended Queue Sample" in the BizTalk Server 2002 Management Pack that is installed in Microsoft Operations Monitor.

  4. Verify that the computer running BizTalk Server is a managed computer agent in Microsoft Operations Monitor.

Note

  • The BizTalk Messaging Services configuration script, SuspendedQueueConfig.vbs, should be run only once. If you want to run the script again, you must first delete any configuration objects previously created by the script in the following order:
    1. Channel: TestChannel

    2. Port: TestPort

    3. Organization: Dest Org

    4. Organization: Source Org

    5. Document Definition: PO

    6. File Receive Function: ReceivePurchaseOrders

To run the sample, complete the following steps:

  1. Ensure that the InvalidPO.xml file is not read-only. To modify this property, right-click the file, click Properties, clear the read-only attribute, and then click OK.

  2. Copy the file InvalidPO.xml into the file receive directory C:\ReceivePO. This will generate a Suspended queue event, which is displayed in the alerts for that agent computer in the Microsoft Operations Monitor console.

Important

  • For the Suspended queue event to be consumed by MOM, the MOM DAS account must be a member of the BizTalk Server Administration group.


Synchronous Orchestration Component

This sample demonstrates a synchronous method for invoking and interacting with an XLANG schedule.

A synchronous call into BizTalk Server expects a response document in return for a request document submitted through the SubmitSync method. For example, in a Web scenario where data flows through HTTP.Request into a Web page (for example, request-submit.asp) and is submitted to BizTalk Server through SubmitSync, the response from BizTalk Server is sent back to the HTTP client by mapping the response document to the HTTP.Response. If the application that produces the response document behind BizTalk Server is accessed through an XLANG schedule, BizTalk Server must implement a synchronous, or blocking, method of invoking and interacting with the XLANG schedule.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\SOC

User's Guide

Before running the sample, complete the following steps:

  1. Open the SOC.dsw Visual C++ workspace. Compile the SOC and REQRES Visual C++ projects. The AIC will be registered with a ProgID of "BizTalk.SyncOrchestration".

  2. Open the XLANG schedule drawing RequestResponse.skv in the Schedule subfolder. Use the Make XLANG RequestResponse.skx command on the File menu to create an XLANG schedule.

  3. Copy the ASP files located in the ASP subfolder to the folder:

    \Program Files\Microsoft BizTalk Server\MessagingManager\pipeline

  4. Create a messaging port that uses an AIC transport type, and is referencing the new BizTalk.SyncOrchestration component.

  5. Create a channel for the messaging port, with any document specification, and a document instance generated from BizTalk Editor. On the Advanced Configuration page, click Advanced. On the Primary Transport tab, click Properties.

  6. On the BizTalk SyncOrchestration Properties page, enter the path and file name of the XLANG schedule in the Skedpath text box. Enter the XLANG port name SyncPort in the Skedport text box.

To run the sample:

Create the IInterchange object and call the SubmitSync method with the channel name and a sample document that uses the Inbound Document Definition specified on the channel. The response will appear as the out parameter of the SubmitSync method call.

Programming Notes

Synchronous COM calls into XLANG schedules are made by invoking a synchronous orchestration component, which is an application integration component (AIC) that implements the IPipelineComponent interface. A synchronous orchestration component uses a property page (.asp) configured with the path of the associated XLANG schedule, which will be used to process messages of a particular schema on the port. When a message arrives at the port through a channel, BizTalk Server invokes a predefined and configured synchronous orchestration component, passing the dictionary object to it. The custom synchronous orchestration component inspects the dictionary object and retrieves the schedule path. It then uses the path to invoke the XLANG schedule, passing along the document in the working_data field of the dictionary object.

The first action in the XLANG schedule is bound to the IRequestResponse::SetRequest(requestDoc) method. The synchronous orchestration component invokes this method and passes the request document to the XLANG schedule for processing. To receive the resulting response document from the XLANG schedule processing, the synchronous orchestration component makes two subsequent calls to the XLANG schedule instance. The first method invoked is IRequestResponse::CompleteProcessing, which sets the response document. Immediately thereafter, the synchronous orchestration component invokes the IRequestResponse::GetResponse method to retrieve the response document. The synchronous orchestration component is blocked until the XLANG schedule processing flows to the action that is bound to the SetResponse port. This call will time out after 120 seconds if no response is available. You can change this default time-out setting of 120 seconds by changing the constant MAX_TIMEOUT_SECS in RequestResponseExample.h.

Note

  • Because the client is blocked while awaiting a response, any issues with time-out limits must be addressed when implementing a synchronous process flow.

The response document is then returned by the synchronous orchestration component to BizTalk Server as a field in the dictionary. BizTalk Server then returns the response document to the Web page that called SubmitSync. The Web page in turn maps the response document to HTTP.Response. To provide COM activation and message delivery from BizTalk Messaging Services to an XLANG schedule, the XLANG schedule must have its first action bound to the IRequestResponse::SetRequest method and its last two actions bound to the actions that will allow the passing of a response document.

Notes

  • If outbound processing by BizTalk Server is required for the response document, the synchronous orchestration component can call into BizTalk Server by using SubmitSync before returning the results to the ASP page through BizTalk Messaging Services.

  • The synchronous orchestration component can be used as an orchestration activation and as a DCOM data delivery mechanism by modifying the synchronous orchestration component to call only SetRequest.


Tracking Database Tasks

This sample contains an SQL script for creating a sample SQL Server Agent job: dtaJob_receipt_monitor_<TrackingDatabaseName>

This job monitors expiring records in the dta_outdoc_details table that are expecting receipts to come back and whose waiting periods have a time-out. By default, this job runs every 30 minutes. It calls the dta_job_mark_expired_outdocs stored procedure.

For a related sample, see the file dta.vbs in the folder \Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Miscellaneous.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\SQLServerAgentJobs

User's Guide

Before running the sample, complete the following steps:

  1. In a text editor, open the DTA_SampleJobs.sql sample file.

  2. Find all instances of the string "%InterchangeDTA%" and replace them with the name of your BizTalk Server Tracking database.

  3. Save the file. You might need to remove the read-only attribute on the file before you can save it.

  4. Start the SQL Server Agent service if it has not already been started.

  5. Start SQL Query Analyzer. On the Start menu, click Programs, click Microsoft SQL Server, and then click Query Analyzer.

  6. In SQL Query Analyzer, connect to the SQL database server to which your BizTalk Server Tracking database belongs.

  7. Change the current database to your BizTalk Server Tracking database.

To run the sample:

  • Open the modified DTA_SampleJobs.sql file and execute a query (press F5).

Programming Notes

If you encounter errors, make sure that the database user account with which you are connecting to the database server has sufficient permissions to create stored procedures and SQL Server Agent jobs. Also make sure that the string find-and-replace in step 2 was done correctly.


Windows Management Instrumentation

This sample illustrates the use of Visual Basic scripts to configure administrative entities such as organizations, document definitions, ports, channels, and receive functions.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\WMI

User's Guide

The sample sets up a file-to-file scenario between two organizations. Each organization is simulated by a directory on the file system. BizTalk Server receives a document from the source organization, and then transforms it and submits it to the destination organization.

To prepare and run the sample, follow these steps:

  1. Run setup.cmd in the sample directory to configure the scenario and run the scripts.

  2. Run the sample scenario by navigating to C:\BizTalkWMI\ and copying the file SourceInstance.xml into C:\BizTalkWMI\SourceOrg.

    This file should be consumed by BizTalk Server, transformed, and submitted to C:\BizTalkWMI\DestinationOrg as the file OutDoc%tracking_id%.xml, where %tracking_id% is a unique ID value.

  3. Run Cleanup.vbs to clear the configuration changes that were made by the sample scripts and to delete c:\BizTalkWMI.

  4. To clear the files stored to WebDAV, navigate to Program Files\Microsoft BizTalk Server\BizTalkServerRepository on the file system and delete DocSpecs\WMISourcePOSchema.xml, DocSpecs\WMIDestPOSchema.xml, and Maps\WMIPOMap.xml.

The two setup scripts that are run in this sample are:

  • ConfigureBTC.vbs. This script creates the organizations for the source and destination, the documents for the source and destination specifications, and the port and channel that are needed for the scenario.

  • ReceiveFunction.vbs. This script configures the File receive function for the scenario.

For more information on these scripts, see the following topics:

  • Creating ConfigureBTC.vbs

  • Creating ReceiveFunction.vbs

These scripts have already been created, but the following programming notes are included to provide a better understanding of how the scripts work.

Programming Notes

The setup.cmd program creates the following folders on your computer:

  • c:\BizTalkWMI. The common folder where all the scenario-related files are copied

  • c:\BizTalkWMI\SourceOrg. The location where BizTalk Server receives documents that are to be sent to the destination organization

  • c:\BizTalkWMI\DestinationOrg. The location where BizTalk Server drops documents that were received from the source organization after processing them

The following files are used in the scenario. You might want to examine them to gain a better understanding. These files are copied to C:\BizTalkWMI and installed in WebDAV:

  • SourcePOSchema.xml. The specification for the source purchase order

  • DestPOSchema.xml. The specification for the destination purchase order

  • POMap.xml. The map that is used for transforming the source specification to the destination specification

The following sections walk through the process of creating ConfigureBTC.vbs and ReceiveFunction.vbs. Double-click the scripts to run them. To avoid name conflict errors, run Cleanup.vbs before attempting to rerun the two configuration scripts. The names of all objects that are created by the scripts in this sample start with "WMI".


Creating ConfigureBTC.vbs

This section walks through the steps that are necessary to set up the two organizations, two document definitions, one port, and one channel that are used in the scenario. After running the script, use BizTalk Messaging Manager to verify that these objects have indeed been added.

  1. Create the Configuration object.

    Calling CreateObject with the ProgID "BizTalk.BizTalkConfig" is the first step in any script that uses the SDK. All other BizTalk Messaging Configuration objects are accessed through this main Configuration object.

  2. Create the source organization.

    Create an Organization object and set its name attribute to the name desired for the source organization. Store the organization handle for use later while configuring the channel.

  3. Create the destination organization.

    Create an Organization object and set its name attribute to the name desired for the destination organization. Store the organization handle for use later while configuring the port.

  4. Add specifications and maps to WebDAV.

    Helper subroutines and functions are used to extract server information and to store the document specifications and map to WebDAV. A WebDAV URL is in the form http://SERVER_NAME/BizTalkServerRepository/. Note that document specifications must be stored in the DocSpecs folder and maps must be stored in the Maps folder under the WebDAV URL.

  5. Create the input document definition.

    Create a Document object that represents the input document specification. Set its name and set its reference to the WebDAV path of the source document specification. Store the document definition handle for use in configuring the channel.

  6. Create the output document definition.

    Create a Document object that represents the output document specification. Set its name and set its reference to the WebDAV path of the output document specification. Store the document definition handle for use in configuring the channel.

  7. Create the port.

    The port represents the destination of this configuration. Set its name, a handle to its destination organization, a constant to indicate its primary transport type (file), and a string to indicate its primary transport address (file://C:\BizTalkWMI\DestinationOrg\OutDoc%tracking_id%.xml). Store the port handle for use in configuring the channel.

  8. Create the channel.

    The channel contains the information that is involved in transforming the document from the source format to the destination format. Set its name, a handle to its source organization, a handle to its associated port, handles to its input and output document definitions, and a reference to the WebDAV path of the map that specifies the transformation.


Creating ReceiveFunction.vbs

This section walks through the steps that are necessary to set up the File receive function that monitors C:\BizTalkWMI\SourceOrg for XML files. After the XML files are picked up, they are processed and sent to the destination organization.

Note that it is important to run this script after the configuration script, because the receive function assumes the existence of an associated channel that is created in ConfigBTC.vbs. After running the script, check to see that the receive function has been created by opening up the BizTalk Server Administrator tool and navigating to the list of receive functions.

  1. Create the locator object.

    Calling CreateObject with the ProgID "WbemScripting.SWbemLocator" is the first step in any WMI-related script. This is the standard way to get an entry point into the WMI objects.

  2. Create the services object.

    To connect to and access a set of related services on a computer, the namespace that identifies that set of services must be given. The target computer defaults to the local computer, and the namespace for the BizTalk Server services is "root/MicrosoftBizTalkServer".

  3. Get the ReceiveFunction class object.

    Use either Get or ExecQuery to retrieve the receive function class. The name of the class is "MicrosoftBizTalkServer_ReceiveFunction".

  4. Spawn an instance of the receive function.

    Use the SpawnInstance_ method on the receive function class to set its attributes.

  5. Set the name of the receive function instance.

  6. Specify the protocol type for this receive function (as File).

    Because the receive function class represents all receive functions, its ProtocolType must be set to 1 (for ADMIN_PROTOCOL_TYPE_FILE) to indicate that it is a File receive function.

  7. Specify the processing server on which this receive function will run.

    In this case, helper functions are used to determine the local computer name.

  8. Specify the name of the group that is associated with this receive function.

    "BizTalk Server Group" is the default name that is set by the script.

  9. Specify the file name mask for this receive function.

    Setting *.xml indicates that all XML files should be picked up from the specified location.

  10. Specify the location to poll for this File receive function.

    This is the location on the file system where the receive function will monitor and pick up source document instances. In this scenario, the PollingLocation is "C:\BizTalkWMI\SourceOrg".

  11. Specify the name of the channel to use.

    This is the channel that was created earlier by ConfigureBTC.vbs.

  12. Set the flag to create the receive function as configured.

    Calling Put_ with the flag set to 2 (wbemChangeFlagCreateOnly) means that we are creating the receive function as configured. The value 2 is the only supported value in the SDK.


BizTalk Orchestration Services Code Samples

Sample files are located in the XLANG Samples folder on the Microsoft BizTalk Server installation drive. Browse to \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples on the installation drive to find the sample files. This is only a relative path. Depending on your installation of BizTalk Server 2002, you might need to modify this path.

  • BizTalk Framework Correlation

  • BizTalk Services Integration

  • Dispatcher Application

  • Dynamic Binding with COM

  • Dynamic Binding with Message Queuing

  • Exception Handling

  • Iteration

  • Nested Transactions

  • Orchestration Services Audit

  • Orchestration Services Audit Client

  • Personalized Queues

  • Queue Listener

  • While Shape

  • XLANG and ASP

  • XLANG Interfaces

  • XLANG Schedule Pooling

  • XLANG Submit Synchronously and Query Asynchronously

  • XLANG Trace

  • XML Translation


BizTalk Framework Correlation

This sample illustrates the use of BizTalk Framework (BTF) 2.0 and orchestration to accomplish stateful interoperability between two applications. It allows two (or more) applications to engage in a potentially long-lived exchange of messages. Each exchange is capable of referring back to the data passed in previous exchanges.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Integrating BizTalk Services

User's Guide

The sample contains the following directories:

  • App contains the BTS SimpleApproval schedule file.

  • BTM2BPO contains a combination application integration component (AIC) and utility component. The AIC part of the component allows a BTF-enveloped message, which includes the <prc> tag, to be sent to the correct existing instance of an orchestration through a message queue or a COM interface (ReceiveMsg). The port name and other options are set through the BizTalk Messaging Manager (Advanced-Properties). In addition to this AIC, this project also contains code needed to envelope an existing message and include the <prc> tag and 'reflect' an enveloped message.

  • ThirdPartyApp contains an application that simulates a third-party application.

  • FileSubmit is the polling location for the ReceiveNewApp receive function.

  • Schema is the directory containing the schema.

  • CorrUtil contains a utility component.

  • SetupFiles contains the scripts to install and uninstall the sample.

To run the sample, follow these steps:

  1. Run setup.cmd to install the sample.

  2. Run SubmitDoc.cmd to drop the NewAppInst.xml file into the FileSubmit directory.

  3. Run ThirdPartyApp\ThirdPartyApp.exe. The Get Message button will retrieve the next message from the RequestApproval queue. It should appear in the edit window. Press the Reflect button to prepare the message for sending back to the schedule. Press Approve to send it to the Approvals queue or Decline to send it to the Denials queue. Message Queuing receive functions will pass these messages back to BizTalk Server and through BTM2BPO back to the schedule.

    The BTS SimpleApproval schedule illustrates two ways in which the response document is delivered to the running schedule instance. The ReceiveApprovalPort port is a Message Queuing port and receives the document through a per-instance queue. The ReceiveDenialPort port is a COM port and receives the document as a parameter to the ReceiveMsg method of the IReceive interface.

  4. View the Application Log by using EventViewer for the name of the port to which the response document was delivered.

  5. Run remove.cmd to uninstall the sample.

Programming Notes

The sample uses:

  • Orchestration to maintain the state of the exchange and determine the sequence of exchanges.

  • BizTalk Framework 2.0 envelopes to pass a state identifier between the applications.

  • BizTalk Server 2002 messaging facilities to abstract individual applications from each other.

BTS SimpleApproval.skv provides a summary view of a sample orchestration using all of the above.


BizTalk Services Integration

Two samples are provided to demonstrate the integration of BizTalk Messaging Services and BizTalk Orchestration Services.

Paths

To locate the sample files for the sample using HTTP as a transport mechanism, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Integrating BizTalk Services\http

To locate the sample files for the sample using Message Queuing and File receive functions, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\Messaging Samples\Integrating BizTalk Services\non-http

User's Guide

Detailed information regarding the HTTP-based sample is provided in the Setting Up HTTP Sample.doc file located in the http folder.

Detailed information regarding the Message Queuing sample is provided in the Setting Up Non-HTTP sample.doc file located in the non-http folder.


Dispatcher Application

This sample demonstrates a dispatcher application that sends and receives documents on behalf of a client application. When a document is sent, the dispatcher saves the "From address" in a database before sending the document and uses the saved address to route the response document to the correct sender.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Dispatcher

User's Guide

This sample consists of the following directories:

  • Apps contains the schedules, a data file, and VBScript files to run the sample.

  • ClientUtil contains a helper component for the ClientApp schedule.

  • DbUtil contains a helper component for simulating a database.

  • DestUtil contains a helper component for the DestApp schedule.

  • DispatchUtil contains a helper component for the DispatchApp schedule.

  • SendUtil contains a helper component for the SendApp schedule.

The setup script, "setup.cmd", does the following:

  • Registers the following components: ClientAppUtil, SendAppUtil, DestAppUtil, DispatchAppUtil, and DbComp.

  • Creates the Message Queuing queues SendDocs, RecvDocs, and UnknownDocs.

To remove the sample, run "remove.cmd".

To run the sample, first run "startDispatchApp.vbs" in the "Apps" directory. This starts the "DispatchApp" schedule and should be run only once. Then run "startClientApp.vbs" in the "Apps" directory. This starts the "ClientApp" and "DestApp" schedules.

The "ClientApp" schedule sends a document to the "SendApp" schedule along with the To Queue and From Queue paths and then waits on a per-instance queue for the response.

The "SendApp" schedule generates a unique token and saves the FromQueue (the per-instance queue of ClientApp) path and the token in a database. The token is added to the document, which is then sent to the To Queue (SendDocs).

The "DestApp" monitors the "SendDocs" queue, reads the document from the queue, extracts the token, creates a response document, adds the token to the response document, and sends the response document to the response queue "RecvDocs".

The "DispatchApp" schedule monitors the "RecvDocs" queue for any document. When the response document is available in the queue, it extracts the token from the document, gets the corresponding delivery queue path from the database, and sends the response document to the delivery queue. If the delivery queue cannot be determined, the document is sent to the "UnknownDocs" queue. After dispatching the document to the correct queue, the "DispatchApp" schedule starts another instance of itself to continue monitoring the "RecvDocs" queue.

The "ClientApp" that is waiting on the per-instance queue receives the response document and processes it.

The "startClientApp.vbs" script can be run any number of times. To terminate the "DispatchApp" schedule, shut down and restart the "XLANG Scheduler" COM+ application by using the Component Services MMC snap-in.

Programming Notes

The "ClientApp" schedule gets the document as an input parameter. The Get Constants action is used to get constant values into the schedule. The Display Input Doc action displays the input document. The Send Doc action uses a helper component to start the "SendApp" schedule and pass it the document, the path of the queue to send the document to, and the path of the per-instance queue where the response should be sent. The Get Response Doc action is used to wait on the per-instance response queue for the response document. The Display Response Doc action displays the received response document.

The "SendApp" schedule receives the document and the From Queue and To Queue paths from the Get Input action. The Save Return Address action generates a GUID token and saves the token and the From Queue address in a database. The token is then added to the document to be sent. The SendDoc action sends the document to the To Queue (SendDocs).

The "DestApp" schedule waits on the "SendDocs" queue for the document. The ReceiveDoc action gets the document from the queue. The CreateResponse action extracts the token from the document, creates a response document, and adds the token to the response document. The SendResponse action sends the response document to the "RecvDocs" queue.

The "DispatchApp" schedule waits on the "RecvDocs" queue for the document. The Get Doc From Queue action gets the document from the queue. The Get Delivery Queue action extracts the token from the document and retrieves the corresponding delivery queue path from the database. The SendDoc action sends the document to the delivery queue.

The "ClientAppUtil" helper component is used by the "ClientApp" schedule to get input parameters, get constants into the schedule, display a message box, start the "SendApp" schedule, and pass parameters to it.

The "SendAppUtil" helper component is used by the "SendApp" schedule to get input parameters and to save the delivery queue path in the database.

The "DestAppUtil" helper component is used by the "DestApp" schedule to extract the token from the input document, create the response document, and add the token to the response document.

The "DispatchAppUtil" helper component is used by the "DispatchApp" schedule to get input parameters, get the delivery queue path from the database, and restart the "DispatchApp" schedule.

The "DbComp" helper component is used by the "SendAppUtil" and "DispatchAppUtil" components to save and retrieve the delivery queue address from a file-based database. The database is simulated by using an XML file, "TrackDb.xml," that is created in the DbUtil directory.

Note

  • To simplify this sample, a file-based database is used. Therefore a transaction shape cannot be used with the database-related actions. Ideally one would use transaction shapes in conjunction with a transactional database to ensure proper recovery in case of failures. The QueueListener sample demonstrates how to use transactions to ensure that a schedule is restarted in the event of an abnormal termination.


Dynamic Binding with COM

This sample demonstrates how to bind dynamically to a COM component. The COM component that the schedule binds to is decided at run time.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Dynamic Binding\COM

User's Guide

The sample consists of the following directories:

  • ScrambleApp contains the scramble sample schedule and the VBScript file to run the sample.

  • ScrambleUtil contains a helper component used to create the COM component to bind to and display messages.

  • ScrambleInterface contains the type library for the IScramble interface.

  • HighSecurityScramble contains a COM component that implements the IScramble interface.

  • LowSecurityScramble contains a second COM component that implements the IScramble interface.

The setup script, "setup.cmd", does the following:

  • Registers the "Scramble" typelib.

  • Registers the following components: HighScramble, LowScramble, and ScrambleHelper.

To remove the sample, run "remove.cmd".

To run the sample, run "startit.vbs" in the "ScrambleApp" directory. The input data to be scrambled is passed to the schedule. When the message High Security Scramble for "Hello World!"? is displayed, click "Yes" to scramble the data by using the "HighScramble" component or click "No" to scramble the data by using the "LowScramble" component. The output is displayed in a message box.

Programming Notes

In this schedule, the "GetInput" action gets the data to be scrambled.

The "GetScrambler" action creates the scrambler component to use based on user selection.

The "ScrambleData" action scrambles the data by using the component created by the previous action. This action can bind to any component that implements the "IScramble" interface.

The "DisplayScrambledData" action displays the output of the "ScrambleData" action.

A helper component, "ScrambleHelper," is used to create the scrambler component and to display messages.


Dynamic Binding with Message Queuing

This sample demonstrates how to bind dynamically to a message queue. The queue path is specified at run time.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Dynamic Binding\Queue

User's Guide

The sample consists of the following directories:

  • QueueBindApp contains the queuebind sample schedule, data file, and VBScript files to run the sample.

  • QueueBindUtil contains a helper component used to process the data file and display messages.

The setup script, "setup.cmd", does the following:

  • Registers the "QueueBindUtil" component.

  • Creates Message Queuing queues named purchase_dept and marketing_dept.

To remove the sample, run "remove.cmd".

To run the sample, run "startit.vbs" in the "QueueBindApp" directory. The "MarketingDeptOrder.xml" data file is sent to the "purchase_dept" queue and the schedule is executed. The schedule reads the data file from the queue and sends an acknowledgment to the "marketing_dept" queue. A message box displays the acknowledgement generated and the reply queue.

Programming Notes

In this schedule, the incoming document received by the "GetOrder" action contains the reply queue location where the acknowledgement needs to be sent.

The "ProcessOrder" action builds the acknowledgement document and extracts the path of the reply queue from the incoming document.

The "DisplayAck" action displays the acknowledgement document and the reply queue location.

The "SendAck" action sends the acknowledgement document to the reply queue that was specified in the incoming document.

A helper component, "QueueBindUtil," is used to process the data file and to display messages.


Exception Handling

This sample demonstrates how to handle an exception.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Transaction Abort

User's Guide

The sample consists of the following modules:

  • A Visual Basic ActiveX DLL contains the component called by the schedule.

  • Abort.vbs contains the code to run the schedule.

The setup script, setup.cmd, registers the abortsample component.

To remove the sample, run remove.cmd.

To run the sample, run Abort.vbs. When you click OK in the dialog box, it sends the string to the schedule. If you have typed Abort, the transaction will be aborted, and you will be shown the appropriate messages.

Programming Notes

This sample demonstrates the use of an abort handler and auto return. When a method call returns a negative HRESULT, then the outer transaction is aborted and the abort handler code for the transaction starts executing. After the abort handler code completes, the command goes to the next action.

If the transaction is aborted then the document is put back on the Received_Doc_In queue (because Message Queuing is used in the transaction) and the abort handler drops a copy of the document into the aborted_doc_out_ queue.


Iteration

This sample demonstrates how to iterate through a list of items and process each item independently based on a condition.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Iteration

User's Guide

Before running the sample, run the setup script setup.cmd.

To run the sample, follow these steps:

  1. Browse to the LineItemsApp folder.

  2. Run the script file startit.vbs.

  3. When prompted, click OK on the message box to continue.

Programming Notes

When run, the "ItemList.xml" file is sent to the "items_in" queue. This file contains a list of items to be processed. The schedule picks up the file from the queue and processes the items in it. Each item is placed in a different "out" queue based on the item type. Any item of unknown type is placed in the "unknown_out" queue. A message box is displayed as each item is processed.

This sample uses a simple counted loop to iterate through the list of items. The GetItemCount action is used to get the maximum iteration count and the While shape is used to control the loop. The Decision shape uses different rules to determine the branch to execute. The Join shape uses an OR join type because only one of the branches will be executed at any given time.

A helper component, "LineItemHelper", is used to increment the loop count, process the data file, and display messages.

To remove this sample, run the script remove.cmd.


Nested Transactions

This sample illustrates nested transactions, aborting a transaction, and compensation.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\NestedTxns

User's Guide

To install this sample, register all the script components in the sample directory.

To run the sample, run the "NestedTxns.wsf" script file.

Programming Notes

The scenario for this sample is ordering an item, submitting payment, receiving the item, returning the item, and having the payment reversed. This scenario is based on a familiar shopping experience, where a merchant accepts returned merchandise and processes a credit-card credit. The credit slip looks like a credit-card debit slip except that it is usually printed in red ink.

The sample encapsulates the entire purchasing cycle in an outer transaction called "Purchase". Inside that transaction is a nested transaction called "Payment". The compensation block for "Payment" includes a transaction named "ReverseCharges". This sample has a total of three transaction envelopes.

The "Purchase" transaction includes an "Order" action; a "Payment" transaction; a "ReceiveItem" action; a decision about whether to keep the item; a branch to return the item, abort, and compensate the payment; and another branch to keep the item. The "Abort" action causes the entire "Purchase" transaction to abort, which, in turn, causes the nested "Payment" transaction to abort. The "Payment" transaction has a compensation block, itself transactional, that carries out the credit or reversal of charges.


Orchestration Services Audit

This sample demonstrates an orchestration audit component.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAudit

User's Guide

There is one interface, IUserEvent.

ServerName is the name of the server associated with your tracking database:

HRESULT Install( /*[in]*/ BSTR ServerName,

Datasource is the name of your tracking database:

/*[in]*/ BSTR Datasource,

/*[in]*/ BSTR Username,

/*[in]*/ BSTR Password,

/*[in,optional]*/ BSTR ApplicationFilter, /*[in,optional, defaultvalue(egAllEvents)]*/ EventGroupTypes EventFilter

HRESULT Uninstall();

Install installs the subscription into the COM+ catalog, and connects to the database. ApplicationFilter can be the name of a COM+ application or the GUID key for that application. EventGroupTypes can be any combination of the enumeration combined by using OR. The default is for all events.

Uninstall removes the subscription from the COM+ catalog and disconnects from the database.

A client should explicitly call Uninstall before releasing the component. Otherwise the subscription will be orphaned until the server is rebooted.

Programming Notes

The database tables and stored procedures are initially built by setup. If you want to restore these, you need to run files in the query analyzer after selecting your tracking database, in the following order:

<InstallationFolder>\Setup\BTS_WorkflowEvents_Schema.sql

<InstallationFolder>\Setup\BTS_WorkflowEvents_Logic.sql

Important

  • This orchestration audit component persists detected events into the InterchangeDTA (default name) database, which is the BizTalk Server Tracking data store. Two tables are used to contain the data for monitored events: dta_wf_WorkFlowEvent and dta_wf_EventData. The first of these contains a row for each event detected and the second contains one or more rows for each property related to a particular event in the first table. Note that the BizTalk Server Tracking user interface might show truncated event data because the columns in the second table (event data) that contain property name and value pairs are set to 100 characters, and actual names and values can exceed this length.


Orchestration Services Audit Client

This sample demonstrates an orchestration audit client.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\WorkFlowAuditClient

User's Guide

To run this application, first register the WorkFlowAudit.dll file by typing regsvr32 WorkFlowAudit.dll at the command prompt. This file is in the <Installation Folder>\SDK\XLANG Samples\WorkflowAudit\bin folder.

After registering this component, run WorkflowAuditClient.exe. When the application is first run, it asks you to enter four parameters. Except for the database user password, the values are taken from the Windows Management Instrumentation (WMI) provider. If you want to change the default settings, type the new values.

When you click Start, the application calls the Install method of the interface in the WorkFlowAudit.dll. The events that are fired by the XLANG Scheduler will be monitored. Do not close the application while tracking the scheduler events. Doing so will terminate the monitoring process.


Personalized Queues

This sample uses a shared queue and per-instance queues. A shared queue called the new-user queue permanently resides at a URL. This queue is associated with the enterprise Web site and with a schedule for creating new users. The client goes to the well-known URL to create a new user account or to log on to an existing user account.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Personalized Queues

User's Guide

This sample uses the items described in the following paragraphs.

Queues

Queues can be inspected from the Management Console (right-click My Computer on the desktop, click Manage, navigate to Services and Applications, Message Queuing, Private Queues).

  • Fixed queue: .\private$\AmysNewUserAccount

  • Account queue: .\private$\AccountQueues{...fresh guid... }

Schedules

Schedules can be inspected with the XLANG Event Monitor that is installed with the BizTalk Server SDK.

  • AmysZoneTop.skv checks that a new user name has been deposited in the top-level queue. In a real application, this would set up user account database tables.

  • AccountSchedule.skv takes command messages in a loop from the per-instance account queue. The loop terminates when the command "Close" comes in.

Windows Batch Command Files

  • Run setup.cmd before running the sample.

  • Run remove.cmd to disable the sample and clean up.

Windows Script Files and Windows Script Components

  • RunMe.wsf runs the sample.

  • VerifyForm.wsc shows that the new user name was received by the new-user queue.

  • RecordQueueName.wsc records the user name and its associated per-instance account queue name in a text-file database.

  • CloseUserAccount.wsc removes the user name from the text-file database.

  • ReportUserCommand.wsc shows that the account schedule has received commands from the SessionWebPage.

  • CreateTopLevelQueue.vbs is run by setup.cmd.

  • DeleteTopLevelQueue.vbs is run by remove.cmd.

HTML pages

  • ClientWebPage.htm allows users to create new accounts or to log on to existing accounts.

  • SessionWebPage.htm feeds user commands to AccountSchedule.skv.

The sample setup script, setup.cmd, creates the unique shared new-user queue.

Note

  • This sample stores the user account database in a text file in the C:\winnt\system32 folder, and assumes that that folder exists. The folder name is hard-coded in only one place in the sample code, so fixing this limitation is easy. Simply edit RunMe.wsf, search for the string "winnt", and change the reference to match the name of your system folder.

To run the sample:

  • Run RunMe.wsf in the ClientApplication folder. Interact with its Web pages and dialogs.

  • Run the Microsoft Management Console (right-click My Computer on the desktop, and then click Manage) to inspect queues and the event log.

  • Run the XLANG Event Monitor to watch the schedules running.

  • Inspect the file C:\winnt\system32\AccountQueuesDB.txt to see the association of user names and per-instance queues.

To remove the sample, run remove.cmd.

Programming Notes

A new user account is represented by a new per-instance queue called the account queue. The account queue is bound to a very-long-lived schedule instance, the account schedule. The account schedule is born (instantiated) at account creation time and lives until account destruction time. Thus, its lifetime is the same as the lifetime of the user account, and this could be measured in years.

We have one new-user queue for the entire enterprise. The enterprise encompasses many user accounts, each with its own account schedule and account queue.

The user logs on to the account by interacting with the account schedule through the account queue. Conceivably, the same technique used to associate many users with one enterprise could be repeated one more level down to associate many sessions with each user. We do not do so in this sample, presuming that two levels of schedules and queues suffice to illustrate the point. However, if session schedules were used, then the account schedule would, in turn, create another per-instance queue called the session queue, which is bound to a session schedule that lives until the user logs off the account.

For now, we assume that each user gets one session, so we combine the functionality of the account with that of the session.

We call this sample Personalized Queues because there is one per-instance queue per user. The most interesting aspect of this application is that the account queue and schedule live as long as the user account. Such a schedule could encapsulate a considerable amount of persistent state information about the user.

The user first approaches the application through a script called RunMe.wsf in the ClientApplication directory. This script launches a Web page called ClientWebPage.htm. To create a new account, the user chooses a user name and a password and enters them into a form on this Web page. When the user clicks Create New User, the script, RunMe.wsf, deposits the new user name in the new-user queue and invokes the schedule in AmysZoneTop.skx.

The job of AmysZoneTop is to create the account queue and instantiate the account schedule, whose XLANG specification is stored in AccountSchedule.skx. Each instance of this schedule lives as long as the user account, and this time could be measured in years.

AccountSchedule creates a new queue for the user. The name of this queue is generated automatically by the system. AccountSchedule invokes a script component, RecordQueueName.wsc, to store the name of the new queue in a system database. For illustration purposes in this sample, the database is stored in a flat text file in the system directory. In a real application, it will be necessary to keep user names and queue names in a SQL Server database.

AccountSchedule then goes into an indefinite loop awaiting commands from the user to arrive on the user's personalized queue.

Note that no real processing of passwords is done in this sample. Password processing is a delicate and critical topic; however, it is beside the point of this sample, which is to illustrate very-long-lived per-instance queues. We therefore avoid the topic in this sample.

The user can also log on to the application by running RunMe.wsf. The script checks the user name in the database and changes to another Web page that allows the user to submit commands to the personalized queue. Some suggested commands appear on the Web page SessionWebPage.htm. These commands only generate pop-up confirmation dialogs.

The one exception is the command Close This User Account. This command removes the user name from the database and shuts down the AccountSchedule, also causing deletion of the personalized queue.

Note that multiple copies of RunMe.wsf can run at one time, and, up to the limitations of contention for the simple text-file "database," all operations of this sample can be interleaved in any way. With user names stored in a SQL Server database, this issue would go away.

The theory articulated here can be verified through the Management Console and XLANG Monitor tools, as well as by inspecting the AccountQueuesDB.txt file over time. Also look at the schedules AmysZoneTop.skv and AccountSchedule.skv in BizTalk Orchestration Designer.

There is one final point worth mentioning. Due to a known limitation of XLANG script binding, it is necessary to have two messages in Port_4 of AccountSchedule. This port reports the user's command to a pop-up dialog box. One of the two messages is outside the loop and corresponds to the first command issued by the user. The other message is inside the loop and corresponds to subsequent commands issued by the user. Two messages are required because XLANG script binding refreshes the contents of a sourced message instance only once. Each iteration of the loop creates a new instance of the message as long as the message is not also present outside the loop. If there were only one message, the pop-up would show only the first command issued by the user, over and over again. The workaround for the limitation is to have two messages of identical form. Note that the Message Queuing binding in Port_2 does not suffer from this limitation, so a single message specification can be used both inside and outside the loop body.


Queue Listener

This sample demonstrates how to continuously monitor a queue for data and start another schedule when new data is available.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\QueueListener

User's Guide

The sample consists of the following directories:

  • ListenerApp contains the sample schedules, a data file, and VBScript files to run the sample.

  • ListenerClientUtil contains a helper component used by the ClientApp schedule.

  • ListenerUtil contains a helper component used by the ListenerApp schedule.

The setup script, setup.cmd, does the following:

  • Registers the ListenerClient component.

  • Registers the ListenerComp component.

  • Creates the Message Queuing queue, Listener.

To remove the sample, run remove.cmd.

To run the sample, first run startListenerApp.vbs in the ListenerApp directory. This starts the ListenerApp schedule and should be executed only once. The ListenerApp schedule monitors the Listener queue for data. When data is available in the queue, it starts the ClientApp schedule, passes the data to it, and starts another instance of itself. To put the data file order.xml into the queue, run File2Queue.vbs in the ListenerApp directory.

The File2Queue.vbs script can be run any number of times. To terminate the queue listener schedule, shut down and restart the XLANG Scheduler COM+ application by using the Component Services MMC snap-in.

Programming Notes

In the ListenerApp, the GetSkedInfo action is used to pass in the path of the ClientApp and ListenerApp schedules. The Receive Doc From Queue action waits until the document is available on the queue. The Start Client App action uses the helper component to start the ClientApp schedule and pass it the document. The Restart Schedule action uses the helper component to start another instance of the ListenerApp schedule before the current instance terminates.

Two transaction shapes are used to ensure that the schedule recovers from any abnormal termination. Transaction1 ensures that the schedule is persisted at the point where it is waiting on the Listener queue. Transaction2 ensures that the schedule is persisted just after the document is read from the queue. If the schedule is terminated at any time, it will be restarted from the last persisted state. It is important to ensure that the database is set up correctly to support persistence.

The ClientApp schedule simply displays the document that is passed to it as input.

The ListenerComp helper component is used by ListenerApp to receive input parameters and start schedules.

The ListenerClient helper component is used by ClientApp to receive input parameters and display the input document.


While Shape

This sample demonstrates how to use the While shape to retry a business process a limited number of times. A loop counter component is used to track the number of times the loop has executed. The loop terminates when the retry count is reached or when the simulated work completes successfully.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Loop

User's Guide

The sample consists of the following directories:

  • RetryApp contains the retry sample schedule and associated script components. It also includes a small VBScript file to run the sample.

  • LoopControl contains a helper component that implements a simple loop counter and supports persistence.

  • LoopUtil contains another helper component to display message boxes indicating the status of the schedule and to prompt for success or failure of the simulated work.

The setup script, setup.cmd, registers the loopcontrol component.

To remove the sample, run remove.cmd.

To run the sample, run startit.vbs in the LoopApp directory. When the schedule runs, it displays a message box to simulate the work being attempted. Click Yes to simulate successful completion of the work, or No to simulate failure. If you click No, the schedule retries the operation and displays the message box again. The schedule proceeds to completion after you click Yes or after the retry limit is reached, and indicates whether the operation was successful.

Programming Notes

This sample is a variation on a simple counted loop. The loop can terminate when the count limit is reached (the retry count) or when the simulated work completes successfully. To exit the loop early, the schedule initializes the loop count to a negative number. The While shape's rule is constructed to exit the loop when the maximum count is reached or when the count is negative.

A "constants" script component is used to supply the schedule with several constant values that are passed to other components.


XLANG and ASP

This sample demonstrates how to call a schedule from an ASP script, passing in data and getting back the result. The script initiates the work and then waits for the result.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\ASP

User's Guide

The sample consists of the following directories:

  • CreditCheckApp contains the creditcheck sample schedule, the ASP page, and a VBScript file to run the sample.

  • CreditCheckUtil contains a helper component to input data into the schedule and return the result.

  • CreditChecker contains a helper component that simulates the credit checking functionality.

The setup script, setup.cmd, does the following:

  • Registers the CreditCheckUtil component.

  • Registers the CreditChecker component.

  • Creates a creditsample Web directory on the default Web site of the local machine.

To remove the sample, run remove.cmd.

To run the sample, follow these steps:

  1. Run startit.vbs in the CreditCheckApp directory. The creditcheck ASP page is displayed in the Web browser.

  2. Enter a number in the text box and click Submit.

Credit will be denied to any number starting with 1 and to any number less then four characters in length.

Programming Notes

This sample uses a Fork shape to start both the credit checks simultaneously and a Join shape to wait for both the credit checks to complete. The ASP script waits on the IsCreditApproved call until the schedule executes the IsCreditApproved action.

Two helper components are used. The CreditCheckUtil component is used to input data into the schedule and return the results to the calling ASP script. The CreditChecker component is used to simulate calls to two different credit agencies to approve the credit.


XLANG Interfaces

This sample demonstrates how to use the XLANG public interfaces to enumerate and manage the running schedule instances and the XLANG host applications.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\PublicInterfaces

User's Guide

When run with no arguments, the sked.vbs script displays its usage options:

usage: cscript sked.vbs <command> <args>

commands:

hosts [computer]

shutdown [computer[!group]]

startup [computer[!group]]

list [computer[!group]]

run [computer[!group]] <schedule path or query> [count]

kill [computer[!group]] <instanceId>

suspend [computer[!group]] <instanceId>

resume [computer[!group]] <instanceId>

The following table shows examples of managing the schedule instances in the default group (host application "XLANG Scheduler") in the local machine.

Option | Result
sked list | Show a snapshot of the running schedules.
sked suspend {de0fff92-4424-4ef5-bdfb-a6b391403b95} | Suspend the schedule with the given ID.
sked resume {de0fff92-4424-4ef5-bdfb-a6b391403b95} | Resume the schedule with the given ID.
sked run c:\MySchedule.skx | Run the Orchestration schedule with the given full path. If the schedule is successfully started, the ScheduleID will be shown.
sked run c:\MySchedule.skx 10 | Run 10 instances of the given schedule.

The following table shows examples of managing the XLANG host applications.

Option | Result
sked hosts | Show the COM+ applications that can host the XLANG schedules.
sked shutdown | Shut down all host applications.
sked startup | Start all host applications.
sked shutdown "!My Host App" | Shut down only the host application named "My Host App".
sked startup "!My Host App" | Start the application "My Host App". (If the default host "XLANG Scheduler" was shut down, it will start too.)
sked hosts OtherMachine | List the host applications on the remote computer OtherMachine.
sked shutdown OtherMachine | Shut down all host applications on the remote machine OtherMachine.
sked startup OtherMachine!MyApp | Start the application MyApp on the remote computer OtherMachine (and possibly the default host "XLANG Scheduler").

The following table shows examples of managing schedules on different host applications and different machines.

Option | Result
sked list "!My Host App" | List the schedules running in "My Host App".
sked list "OtherMachine!MyApp" | List the schedules running in the application "MyApp" on the remote computer OtherMachine.
sked list OtherMachine | List the schedules running in the default host application ("XLANG Scheduler") on the remote computer OtherMachine.
sked run !MyApp c:\MySked.skx | Run the schedule MySked.skx in the application MyApp on the local machine.
sked run OtherMachine!MyApp \\server\share\MySked.skx | Run the schedule MySked.skx in the application MyApp on the remote machine OtherMachine. Note that the .skx file should be accessible to the application, for example, on a public share.
sked suspend !MyApp {de0fff92-4424-4ef5-bdfb-a6b391403b95} | Suspend the schedule with the given ID, which is running in the application MyApp on the local machine.
sked resume OtherMachine!MyApp {de0fff92-4424-4ef5-bdfb-a6b391403b95} | Resume a schedule running in the application MyApp on the remote computer OtherMachine.
sked kill OtherMachine {de0fff92-4424-4ef5-bdfb-a6b391403b95} | Terminate a schedule running in the default host on the remote computer OtherMachine.

Programming Notes

The XLANG public interfaces are available from the type library "XLANG Scheduler Runtime Type Library."

The sked.vbs script uses the public interfaces IWFSystemAdmin, IWFGroupAdmin, and IWFWorkflowInstance, as well as some COM+ admin interfaces and objects.

To list the running schedules or to suspend, resume, or terminate a schedule, the moniker for the Group Manager of the given application is constructed, and its IWFGroupAdmin interface is used.

To shut down or start all host applications, or to shut down a particular application, the IWFSystemAdmin interface is used.

To start a particular application, its moniker is constructed and used in GetObject.

To run a schedule, the proper moniker is constructed (for example, "sked://"+ the computer name +"!" + the application name +"/"+schedule path) and is used in GetObject. To obtain the ID and the module name of the newly started schedule, its IWFWorkflowInstance interface is used.

To list the XLANG host applications, the COM+ admin objects are used.


XLANG Schedule Pooling

This sample demonstrates how to use the pooling feature that is built into the XLANG Scheduler Engine. This feature helps running schedules to effectively use system resources. This sample also demonstrates the new BizTalk Server 2002 feature that makes the instance ID available.

BizTalk Server 2002 provides the capability to control the load on the XLANG Scheduler Engine by limiting the number of schedules that can be run simultaneously at any given time. If many schedules are active simultaneously, the server will constantly context switch and will use the operating system resources inefficiently.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\Schedule Throttling

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup

  • Run the Sample

Programming Notes

The following instructions walk through the process of setting up the pooling sample that utilizes the load-limiting capabilities of the BizTalk Server 2002 XLANG Scheduler Engine.

This schedule contains an action that is bound to a method called MessageBox on the script component. That method takes the instance ID of the schedule instance as a parameter, demonstrating one use of the new BizTalk Server 2002 feature that makes the instance ID available. As its name implies, the method displays a message box containing the instance ID. After the user clicks the message box, the schedule completes.


Preliminary Setup

Before you run the sample, you must complete the following tasks:

  • Register the Script Component

  • Run the Setup Script


Register the Script Component

In this procedure, you register the script component that is used by the sample schedule.

  1. Right-click the icon that represents the script component ThrottlingSample.wsc.

  2. Click Register.


Run the Setup Script

In this procedure, you run the script that sets up the pooling properties.

  1. Double-click the script ThrottlingConfig.vbs. Input boxes appear and request configuration information.

  2. Provide the requested information in each box and then click OK. The script uses this information to set the activation properties of the pool in which the sample schedule will run.


Run the Sample

In this procedure, you run the sample that demonstrates the pooling feature.

  1. Double-click the script ThrottlingSample.vbs. An input box appears and asks for the number of schedule instances to run.

  2. Enter the desired number of schedule instances to run and click OK.

  3. Monitor the number of running XLANG schedule instances by using XLANG Event Monitor (XLANGMon.exe). This number should not exceed the maximum pool size that was configured by using the setup script.

    Clicking the message box that a schedule instance displays allows that instance to complete and thereby make room for one more instance in the pool. If the pool becomes full before all the requested schedule instances have been activated, the next instance cannot be activated and will eventually time out. Thus, if you allow schedule instances to fill the pool (by not clicking their message boxes), you will eventually see a different message box declaring that activation of the next schedule instance has timed out.

  4. To rerun the sample with different pooling properties, rerun the setup script, ThrottlingConfig.vbs, and then start again at step 1 of this procedure.


XLANG Submit Synchronously and Query Asynchronously

This sample shows how to make an ASP page submit information into a XLANG schedule and then retrieve information without having to be interlocked with the running schedule.

Note

This sample is an extension of the ASP sample that shows the interaction between an ASP page and an XLANG schedule.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANG_ASYNC

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup

  • Modifying the Default Configuration

  • Running the Sample


Preliminary Setup

Complete the steps outlined in this section to configure your computer to run the sample.

Configuring the Sample Objects and Web Pages

The default configuration of this sample assumes that BizTalk Server 2002 and SQL Server 2000 are installed on the local computer. If you need to change the configuration, modify the values of DBHost as described in Modifying the Default Configuration.

To set up the required table, register COM objects, and configure a virtual Web directory, run SETUP.CMD located at \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANG_ASYNC\setup.


Modifying the Default Configuration

For the ASP page to interact asynchronously with the XLANG schedule, this sample uses a shared SQL table to store state and XLANG-to-ASP return information. Both parts of the sample (the ASP page and the XLANG schedule) share the COM object in XLANG_SAMPLE_ASYNC_SQL.DLL to communicate to the SQL table. The default configuration of the sample is to use the instance of SQL Server on "localhost."

Note that both groups of steps must be performed.

To change the COM object configuration:

  1. Change the default read-only status of the files in \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANG_ASYNC\SQL_Object to read/write. (Alternatively, copy the files to another working directory and make that copy writable; note that later you will have to re-register the COM object for this new location.)

  2. Using Visual Basic, open the project XLANG_SAMPLE_ASYNC_SQL.VBP.

  3. Open the module "globals" (the file globals.bas).

  4. Modify the variable DBHost to reference the desired instance of SQL Server.

  5. Make the project to rebuild XLANG_SAMPLE_ASYNC_SQL.DLL.

  6. If you have moved its location, remember to re-register the DLL using regsvr32.

To build the shared database on a computer other than "localhost":

  1. Change the default read-only status of the file \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANG_ASYNC\SETUP/SETUP_DB.CMD to read/write.

  2. Edit the file and change the two instances of "-S localhost" to the appropriate computer name.

  3. Save and run this modified setup script.

Security

Note that the virtual Web directory created for this sample uses Windows NT Authentication. A user accessing the sample Web page and possibly the service account for BizTalk (service BTSSvc) needs to have permission to the shared database. Generally the user of this sample is part of the "BizTalk Administrators" group and is the creator of the table, so there should be no problem running the sample.

Any other configuration or situation might require adjustments of security permissions in the SQL Server Enterprise Manager.


Running the Sample

To run the sample, you can run \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANG_ASYNC\RUN_SAMPLE.CMD.

Alternatively you can access http://localhost/sync_async_xlang/async.asp.

You can also complete the following steps:

  1. From a remote computer substitute the appropriate host name for "localhost."

  2. For "name of fruit", enter apples (note that this program is case-sensitive).

  3. For the amount enter any number (there are 50 "apples" in the warehouse).

  4. Click Submit.

The Web page will update with a blank table with a button labeled Check_Details on WorkItem #. At this point the ASP page has broken free of the XLANG schedule. Clicking the Check_Details… button repeatedly will update the blank table.

Approximately 30 seconds after submitting (for "apples"), the state column will change from "0 processing" to "1 Complete" and return information will appear in the strSKU and iAmountAvailable columns.

To contrast this with the normal synchronous interaction with XLANG, access the page:

http://localhost/sync_async_xlang/async.asp

This page (and its associated XLANG schedule) will not completely reload until the XLANG schedule returns information.


Programming Notes

This sample addresses the fact that some workflows in an XLANG schedule can take a long time to complete, especially when a schedule has to send a document or message to another organization and wait for returned information. BizTalk Server can handle the long delays, but a user waiting for an order to complete on a Web page might not.

This sample shows a technique to allow the user to submit information to an XLANG schedule and then quickly separate from the processing. The user can then asynchronously query the state of the processing.

For this sample, the business model is a simulated fruit warehouse. The user will request an inventory check for, say, "234 apples" and the warehouse will return a document with the available number of apples and the order code (SKU) for an actual purchase. To make the sample interesting, the processing takes a different amount of time depending upon what type of fruit is selected, as follows:

  • Bananas take 10 seconds to check inventory.

  • Apples take 30 seconds.

  • Oranges take 50 seconds.

  • Anything else is not in stock, and takes 0 seconds.

Note

  • To simulate the processing delay, the business code uses the Sleep function. This function should not be used in a production COM object because it will do things like prevent the long-running XLANG process from being dehydrated. It is used here to simplify the non-essential part of the sample code.

Technique Used

To allow the ASP page to work asynchronously with the XLANG schedule, the sample does the following:

  • The user fills out the form on the ASP page and clicks Submit.

  • The ASP page invokes the XLANG schedule.

  • Synchronously, the ASP page passes the request information to the schedule through a shared COM object.

  • The XLANG schedule registers for a row in a shared SQL table. The unique key for this row is used as a token for the working instance. The row now contains information in a "not ready" state.

  • The ASP page synchronously retrieves the token from the XLANG schedule (through the shared COM object) and is now free from the XLANG schedule.

  • The ASP page can now query the shared SQL table at any time to check for the change of state of the row.

  • The XLANG schedule does its processing. When complete, it updates the row in the shared table with returned data and changes the state to "completed."

  • Eventually, the ASP page query of the row will get the updated state and the returned information.

The following paragraphs provide information about the modules used in this example.

Inventory_OBJECT\XLANG_sample_fruit.dll

This is the simulated business process. Rather than complicating the sample with a complex workflow, this COM object simulates a long-running process.

Public Sub check_storeroom(ByVal str_in_type As String, _

ByVal i_in_amount_requested As Integer, _

ByRef str_out_SKU As String, _

ByRef i_out_amount_available)

This takes a fruit name (str_in_type) and a desired amount (i_in_amount) and eventually returns an order code (str_out_SKU) and amount available (i_out_amount_available).

Note

  • To simulate the processing delay, the business code uses the Sleep function. This function should not be used in a production COM object because it will do things like prevent the long-running XLANG process from being dehydrated. It is used here to simplify the non-essential part of the sample code.

ASP_OBJECT\XLANG_sample_ASP.dll

This is the linking COM object between the ASP page and the XLANG schedules. It is similar to the object used in the XLANG_Samples\ASP example.

It performs two tasks:

  • Provides the synchronization points between the ASP page and the XLANG schedules

  • Persists returned information from XLANG for the ASP to use

Note that this COM object is shared between the blocking.asp sample and the async.asp sample.

Persisted data for blocking.asp are the variables:

Dim stored_SKU As String

Dim stored_amount_available As Integer

Persisted data for async.asp is the variable

Dim stored_WorkID As Integer

This stub function is used by both blocking.asp and async.asp to pass information into their associated XLANG schedules:

Public Sub Request_fruit_amount(ByVal fruit_type As String, _

ByVal amount As Integer)

Note

  • The body of this method is never used. The XLANG schedule performs a "wait for synchronous call." This means that the XLANG schedule provides the body for the method and will wait until another program (the ASP page sharing the COM object) calls the method. The XLANG implementation then provides the arguments that are provided to the data page of the schedule.

For the blocking.asp sample, this method is used by blocking_sample.skv to store return data into the persisted data area:

Public Sub Store_fruit_response(ByVal SKU As String, _

ByVal amount_available As Integer)

For the blocking.asp sample, these methods are used by the ASP page to retrieve the persisted data:

Public Function Get_fruit_SKU() As String

Public Function Get_fruit_amount_available() As Integer

Notes

  • The XLANG schedule blocking_sample.skv performs a "wait for synchronous call" on these methods. This must be done for the sked object that calls these methods so that the VBScript code in the ASP page can access them.

  • In the schedule, the order in which the XLANG schedule waits for these methods must match exactly the order in which the ASP page will call them.

Compared to the blocking.asp sample, the mechanism in async.asp to communicate between the XLANG and ASP is simpler.

The ASP page still calls the Request_fruit_amount method but then uses this method to get a token for the row in the shared table:

Public Function Get_async_WorkID() As Integer

The XLANG schedule async_sample.skv gets the token and stores it through this method:

Public Sub Store_async_WorkID(ByVal iWorkID As Integer)

The XLANG schedule async_sample.skv then synchronizes with the ASP page with Get_async_WorkID

Note

  • The XLANG schedule async_sample.skv synchronizes with the ASP page at only two places. One is at the beginning of the schedule to get the input information and the other is to immediately pass the token information through Get_async_WorkID. The schedule then runs asynchronously from this point onward.

SQL_object\XLANG_SAMPLE_ASYNC_SQL.dll

This is the shared COM object between async.asp and async_sample.skv that handles working with the common SQL table:

Function Register_for_work_id(ByVal strFruitType, _

ByVal iRequestAmount) As String

This method is used by the XLANG schedule async_sample.skv to create a new row in the shared table. The method populates it with the input information and sets the state column (iState) to 0 (processing). The method returns a unique key for the row (WorkID). Any references to the row must use this unique key.

Public Function Update_work_entry(ByVal iWorkID As Integer, _

ByVal iState As Integer, _

ByVal strSKU As String, _

ByVal iAmountAvailable As Integer)

This method is used by the XLANG schedule async_sample.skv when the processing is complete to update the row with the returned information.

Public Function GetWorkItemXML(ByVal iWorkID As Integer) As String

This method is used by async.asp to populate a frame with the state of the row. The returned sting is SQL XML format (SQL table was accessed as "FOR XML AUTO")

Async.asp

This is the user page that invokes the XLANG schedule and then can query for returned information asynchronously.

Note

  • The following code invokes the XLANG schedule and exposes the interface methods used to synchronize with it:

sSkedUrl = "sked:///" & sPath & "async_sample.skx/ASP_async_Interface"

This references the schedule file. Note the addition of the COM interface that should be exposed.

set sked = GetObject(sSkedUrl)

This actually starts the XLANG schedule, which now waits for the first call to request_fruit_amount.

sked.request_fruit_amount sText, sAmount

iWorkID = sked.Get_async_WorkID()

These two lines pass information in and retrieve the token from the schedule (the only synchronous operation with the schedule).

The rest of the ASP page creates a button to invoke Work_item_details.asp to fill the frame at the bottom of the page.

Work_item_details.asp

This ASP page calls GetWorkItemXML to retrieve the state of the schedule's operations and formats the XML for rendering as a table.

The rendering is done by an XSLtransform in workitem_details.xsl.


XLANG Trace

This sample uses a COM object in the library XLANG_TRACE.dll to insert tracing operations into an XLANG schedule. This COM object helps trace and debug problems in an XLANG schedule by writing data from the running schedule into a logging table. Any data that is used in the schedule can be sent to the logging table, including the XML documents being passed between actions in the schedule.

Note

  • This sample is intended only for debugging a specific XLANG schedule. In a production environment, the tracing COM object should not be used because it can significantly impact XLANG schedule processing performance.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANGTRACE.

User's Guide

To prepare and run the sample, follow these steps:

  • Preliminary Setup

  • Modifying the Default Configuration

  • Using the Tracing Component

  • Viewing the Trace Results

Programming Notes

After the XLANG_TRACE COM object is registered on a computer running BizTalk Server, you can add one or more bindings to this object in your existing XLANG schedule files. After the object is bound to a schedule, you need to modify the data mapping in the schedule to specify the data being traced. The XLANG_TRACE object contains the following input parameters for recording schedule data:

message_label

String to describe the name of the Action shape.

message_ID

String to hold a unique identifier for this schedule, such as the instance GUID of the schedule.

message_UserKey

String to store a unique document identifier, such as a purchase order number.

message_body

String to store a large amount of data, such as an entire XML document in a message.


Preliminary Setup

Complete the steps outlined in this section to configure your computer to run the XLANG tracing sample.

Configuring the Tracing Database

The default settings of the XLANG tracing sample require a database for storing the tracing data. However, you can modify these settings to use Event Logging instead of, or in addition to, a database. If you do not want to use a database, proceed to the next section, Modifying the Default Configuration.

To use a database for the tracing data, run the command script setup_db.cmd that is located on the installation drive at \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANGTRACE\setup. This command script file creates the following items:

  • A database named XLANG_TRACE

  • A table in this database named trace_table

  • A stored procedure in this database named Log_text_message

Note

  • If you choose to run this file on a remote computer, you must modify the DBHost value in the Globals.bas file, as described in Modifying the Default Configuration.

Registering the Tracing Component

To register the XLANG_TRACE.dll component, run the command script register_COM.cmd that is located on the installation drive at \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANGTRACE\setup. The COM object XLANG_TRACE.dll must be registered on each computer that uses it.


Modifying the Default Configuration

The XLANG_TRACE sample can be configured to output tracing information into an SQL table or to the system Event Viewer. By default, the XLANG_TRACE COM object (XLANG_TRACE.dll) is configured to store the trace information in a SQL Server database on the local computer ("localhost"). This configuration assumes that both BizTalk Server and SQL Server are running on the local computer.

To change the settings of the tracing object, you must edit the global variable values in the file Globals.bas, and recompile the Microsoft Visual Basic project named XLANG_TRACE.vbp. The following global variables can be modified:

DBHost

String containing the host name of the computer running SQL Server where the tracing data will be stored. An empty string ("") is used to indicate that tracing data will not be stored to a database. The default value is "localhost".

EventLogging

Boolean that indicates whether tracing data should be logged in the system Event Viewer. A value of True indicates that tracing data is logged in the Event Viewer. The default value is False.

The other variables in the Globals.bas module contain information about the database (DBTraceDatabase) and table (DBTraceTable) names. It is not necessary to modify these values. If these values are changed, the file dumptable.xsl will also require modification.

After you have modified the global variables and saved the Visual Basic project, recompile the project into a new DLL file.

Notes

  • If any changes are made to the COM object after its first use, you might need to stop and restart the XLANG Scheduler Engine to release the cached version of the COM object before the new version can be run. For information on stopping and restarting the XLANG Scheduler Engine, see the following topics in the BizTalk Server Help file:
    • Shut down all XLANG applications

    • Restart all XLANG applications
  • If the dumptable.asp page is used to view the tracing data before changes are made to the tracing object, Internet Information Services (IIS) might also use a cached version of the original object. For more information, see Restarting BizTalk Server and Internet Information Services.

  • When event logging is enabled, the events appear in the application log. The XLANG tracing entries will have a Type value of Information, and a Source value of VBRuntime.


Restarting Biztalk Server and Internet Information Services

If a BizTalk Server schedule or an ASP page references a COM object, it will be locked "in use" and cannot be replaced by a recompile. These services must be restarted to release the cached COM object and allow the COM object to be recompiled.

This procedure explains how to restart Internet Information Services (IIS).

  1. On the Start menu, point to Settings and click Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Computer Management.

  4. In the Computer Management console tree, expand Services and Applications and then click Internet Information Services.

  5. On the Action menu, click Restart IIS.

    The Stop/Start/Reboot dialog box appears.

  6. Verify that Restart Internet Services on computer_name is selected.

  7. Click OK to restart IIS.

This procedure restarts the Biztalk Server service that will also hold onto a COM object.

  1. Still using Computer Management, click the Services node and click XLANG Schedule Restart Service near the bottom.

  2. On the Action menu, click Restart


Using the Tracing Component

After the tracing component has been configured and registered, you can add one or more references to it in any XLANG schedule. To add the tracing component to an XLANG schedule, complete the following steps:

  1. Open your XLANG schedule drawing (.skv) in BizTalk Orchestration Designer.

  2. Add a COM component implementation shape to the right side of the Business Process drawing.

  3. Complete the COM Component Binding Wizard and select the Logger class from XLANG_TRACE in the list of registered components.

  4. Add an Action shape to the left side of the Business Process drawing.

  5. Connect the process flow arrow from the bottom of the preceding shape into the top of the new Action shape.

  6. Connect the process flow arrow from the bottom of the new Action shape into the top of the following shape.

  7. Click the new Action shape to highlight it, and then drag the connection point on the right side of the Action shape to the connection point on the left side of the port that is associated with the XLANG_TRACE COM object.

  8. Complete the Method Communication Wizard.

  9. Re-map the data flow on the Data page. You can set the input values of the XLANG_TRACE LogStringMessage method by using other messages on the Data page or by using constants.

  10. Save and re-compile your XLANG schedule. It might be helpful to save the file as a separate tracing version by using a different name. For example, a new version of a file named myschedule.skv can be named myschedule_trace.skv.

  11. Run the new schedule and view the tracing information in the database or in Event Viewer, depending on your configuration.

For additional information about using BizTalk Orchestration Designer, see the BizTalk Server Help file.


Viewing the Trace Results

The tracing information that is stored in the database can be viewed directly through SQL Server. To view this data, follow these steps:

  1. On the Start menu, point to Programs, point to Microsoft SQL Server, and click Enterprise Manager.

  2. Expand the Microsoft SQL Servers tree, and expand the group and server name of the computer that is running the database for the XLANG tracing information.

  3. Expand the Databases folder, expand the XLANG_TRACE database, and then click Tables.

  4. Right-click the table named trace_table, and then point to Open Table and click Return all rows.

The tracing information that is stored in the database can also be accessed by using the file Dumptable.asp located in the folder \Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XLANGTRACE\ASP on the BizTalk Server installation drive.

Notes

  • To use the ASP file, you must either map the ASP folder as a virtual directory in Internet Information Services (IIS), or place the contents of the ASP folder into an existing virtual directory.

  • You might need to add the Internet user account (ISR_computername) to allow IIS access to the database.

Event Viewer logs can be accessed in the Computer Management console.


XML Translation

This sample demonstrates how to use the SubmitSync method of BizTalk Server to perform an XML transformation by using BizTalk Orchestration Services.

Path

To locate the sample files, browse to the following folder on the BizTalk Server installation drive:

\Program Files\Microsoft BizTalk Server\SDK\XLANG Samples\XML Translation

User's Guide

The sample consists of the following modules:

  • A Visual Basic ActiveX DLL contains the component called by the schedule to get the submission parameters.

  • The loopback.vbs script contains the code to run the schedule.

The setup script, setup.cmd, does the following:

  • Registers the ProcessDoc component

  • Creates message queues.

  • Creates BizTalk Configuration objects.

To remove the sample, run remove.cmd and delete the copied files from the directories.

To run the sample, run loopback.vbs. The script sends SamplePOData.xml to the received_in message queue and starts the loopback.skx schedule.

Programming Notes

This sample demonstrates the use of the SubmitSync call using BizTalk Orchestration Services to do the XML transformations. The schedule picks up the document from the received_in queue and then calls GetSubmitParams to get parameters for calling SubmitSync. When the SubmitSync call is returned, the transformed document is returned in the out parameter, which is displayed and then sent to the biztalk_out message queue.


BizTalk Server Reference

This section contains the following topics:

  • Messaging Services Reference

  • Documents Reference

  • Custom Components Reference

  • Orchestration Services Reference

  • Managing and Monitoring Reference

  • Error Messages


Messaging Services Reference

This section provides reference information about application programming interfaces (APIs) used by Microsoft BizTalk Server 2002 for both C++ and Microsoft Visual Basic programming.

Reference information is provided for all interfaces, methods, properties, and enumerations exposed for accessing messaging services:

  • Interfaces

  • Enumerations

In addition, a complete list of Error Messages is provided.


Interfaces

The following COM interfaces are documented:

  • IBizTalkBase

  • IBizTalkCertificateInfo

  • IBizTalkChannel

  • IBizTalkConfig

  • IBizTalkDocument

  • IBizTalkEndPoint

  • IBizTalkEnvelope

  • IBizTalkLoggingInfo

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

  • IBizTalkServiceWindowInfo

  • IBizTalkTransportInfo

  • IDictionary

  • ISimpleList


IBizTalkBase

Defines common methods and properties inherited by several messaging services objects.

Hierarchy

IDispatch

|--IBizTalkBase

Declaration

[Visual Basic]

Class IBizTalkBase

[C++]

interface IBizTalkBase : IDispatch

Members

IBizTalkBase defines the following properties:

Property | Description
DateModified | Contains the date and time at which the information in the object was created or last modified.
Handle | Contains the handle to the object.
Name | Contains the name of the object.

IBizTalkBase defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
Load | Loads a specified object in memory.
LoadByName | Loads a specified object by name in memory.
Remove | Removes the object from the database.
Save | Saves the object in the database.

Remarks

The following interfaces inherit properties and methods from IBizTalkBase:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Note

  • The methods and properties of IBizTalkBase are always invoked on the objects listed above, rather than by creating an actual IBizTalkBase object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Clear Method

Clears the object from memory.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Sub Clear( )

[C++]

HRESULT Clear( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

After Clear is called, all member variables of the object in memory are initialized to their default values.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Create Method

Creates a new object in the database.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Function Create( ) As Long

[C++]

HRESULT Create(

long* BiztalkObjectHandle

);

Parameters

BiztalkObjectHandle

[out, retval] In C++, contains a handle to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a handle to the object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The Name property must be set before calling this method. Name must be unique across the database for each object type. Create updates the DateModified property.

When creating any object that refers to an XML document specification or map located outside your local domain, you might receive an error. If an error occurs, download and configure the WinHTTP proxy utility. To download this utility, go to the Microsoft MSDN Web site at msdn.microsoft.com/downloads/default.asp, and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


DateModified Property

Contains the date and time at which the information in the object was created or last modified.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Property Declaration

[Visual Basic]

Property DateModified As String

[C++]

HRESULT get_DateModified(

BSTR* Modified

);

Parameters

Modified

[out, retval] In C++, contains the date modified. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the date modified.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

The format for the Modified string is yyyy-mm-dd hh:mm:ss. The time is in coordinated universal time (UTC). The server sets this property when the Create or the Save method is called for the object.

The following objects support this property:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Handle Property

Contains the handle to the object.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Property Declaration

[Visual Basic]

Property Handle( ) As Long

[C++]

HRESULT get_Handle(

long* BiztalkObjectHandle

);

Parameters

BiztalkObjectHandle

[out, retval] In C++, contains the handle to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property contains the handle to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

The following objects support this property:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Load Method

Loads a specified object in memory.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Sub Load( _

BiztalkObjectHandle As Long _

)

[C++]

HRESULT Load(

long BiztalkObjectHandle

);

Parameters

BiztalkObjectHandle

[in] Contains the handle to the object to load.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Load calls the Clear method internally before loading the object.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


LoadByName Method

Loads a specified object by name in memory.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Sub LoadByName( _

Name As String_

)

[C++]

HRESULT LoadByName(

BSTR Name

);

Parameters

Name

[in] Contains the name of the object to load.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

LoadByName calls the Clear method internally before loading the object.

Names have a maximum length of 64 characters.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Name Property

Contains the name of the object.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--LoadLat_SDK_BTCOM_Base_GQNF

|--LoadByName

|--Name

|--Remove

|--Save

Property Declaration

[Visual Basic]

Property Name( ) As String

[C++]

HRESULT get_Name(

BSTR* Name

);

HRESULT put_Name(

BSTR Name

);

Parameters

Name

[out, retval], [in] In C++, contains the name of the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The server requires the Name property. It must be set before calling the Create or the Save method for the object. Name must be unique across a database for each object type and must be at least one character long. Names have a maximum length of 64 characters.

The following table lists names reserved for use by BizTalk Server:

Name | Object type
Reliable Message Acknowledgement Port | IBizTalkPort
Reliable Message Acknowledgement Channel | IBizTalkChannel
BizTalk Canonical Receipt | IBizTalkDocument
Reliable Messaging Acknowledgement | IBizTalkDocument
Reliable Messaging Acknowledgement SMTP From Address | IBizTalkOrganization
Home Organization | IBizTalkOrganization

The following objects support this property:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Remove Method

Removes the object from the database.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Sub Remove( )

[C++]

HRESULT Remove( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The object cannot be removed if any other object refers to it.

A BizTalkOrganization object cannot be removed if it is the default organization. Before it can be removed, the IsDefault property must be set to False, and another organization must have the IsDefault property set to True.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Referential Integrity


Save Method

Saves the object in the database.

Member List

IBizTalkBase

|--Clear

|--Create

|--DateModified

|--Handle

|--Load

|--LoadByName

|--Name

|--Remove

|--Save

Method Declaration

[Visual Basic]

Sub Save( )

[C++]

HRESULT Save( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The Save method updates the DateModified property.

When saving any object that refers to an XML document specification or map located outside your local domain, you might receive an error. If an error occurs, download and configure the WinHTTP proxy utility. To download this utility, go to the Microsoft MSDN Web site at msdn.microsoft.com/downloads/default.asp, and browse to the WinHTTP Proxy Configuration Utility page, which is located in the XML chapter of the Web Development book.

The following objects support this method:

  • IBizTalkChannel

  • IBizTalkDocument

  • IBizTalkEnvelope

  • IBizTalkOrganization

  • IBizTalkPort

  • IBizTalkPortGroup

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkCertificateInfo

Configures a certificate associated with an IBizTalkPort or IBizTalkChannel object.

Hierarchy

IDispatch

|--IBizTalkCertificateInfo

Declaration

[Visual Basic]

Class BizTalkCertificateInfo

[C++]

interface IBizTalkCertificateInfo : IDispatch

Members

IBizTalkCertificateInfo defines the following properties:

Property | Description
Name | Contains the name of the certificate.
Reference | Contains a reference to the certificate in the certificate store.
Store | Contains the store type for the certificate.
Usage | Contains the type of use for the certificate.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Certificates


Name Property

Contains the name of the certificate.

Member List

IBizTalkCertificateInfo

|--Name

|--Reference

|--Store

|--Usage

Property Declaration

[Visual Basic]

Property Name As String

[C++]

HRESULT get_Name(

BSTR* Name

);

Parameters

Name

[out, retval] In C++, contains the name of the certificate. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the certificate.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Reference Property

Contains a reference to the certificate in the certificate store.

Member List

IBizTalkCertificateInfo

|--Name

|--Reference

|--Store

|--Usage

Property Declaration

[Visual Basic]

Property Reference As String

[C++]

HRESULT get_Reference(

BSTR* Reference

);

HRESULT put_Reference(

BSTR Reference

);

Parameters

Reference

[out, retval], [in] In C++, contains the certificate reference. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the certificate reference.

In C++, this property returns an HRESULT value, indicating success or failure.

For a list of all error messages returned by BizTalk Server, see Error Messages.

Note

  • In addition to the HRESULT values listed on the error messages page, the put method returns CryptoAPI errors. Additional information about CryptoAPI is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string (""). A reference to a certificate should be obtained by using the Certificates property on the IBizTalkConfig object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Store Property

Contains the store type for the certificate.

Member List

IBizTalkCertificateInfo

|--Name

|--Reference

|--Store

|--Usage

Property Declaration

[Visual Basic]

Property Store As BIZTALK_STORE_TYPE

[C++]

HRESULT get_Store(

BIZTALK_STORE_TYPE* StoreType

);

HRESULT put_Store(

BIZTALK_STORE_TYPE StoreType

);

Parameters

StoreType

[out, retval], [in] In C++, contains the store type for the certificate. Valid values for this parameter are defined by the BIZTALK_STORE_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_STORE_TYPE enumeration.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The store, which contains the certificate, is determined by the use of the certificate as follows:

Certificate type | Store
Decryption | MY
Encryption | BIZTALK
Signature | MY
Verify signature | BIZTALK

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Usage Property

Contains the type of use for the certificate.

Member List

IBizTalkCertificateInfo

|--Name

|--Reference

|--Store

|--Usage

Property Declaration

[Visual Basic]

Property Usage As BIZTALK_USAGE_TYPE

[C++]

HRESULT get_Usage(

BIZTALK_USAGE_TYPE* UsageType

);

Parameters

UsageType

[out, retval] In C++, contains the usage type for the certificate. Valid values for this parameter are defined by the BIZTALK_USAGE_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_USAGE_TYPE enumeration.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkChannel

Configures a channel for processing documents.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkChannel

Declaration

[Visual Basic]

Class BizTalkChannel

[C++]

interface IBizTalkChannel : IBizTalkBase

Members

IBizTalkChannel defines the following properties:

Property | Description
Comments | Contains user comments for the object.
ControlNumberValue | Contains the value of the group control number.
DateModified | Contains the date and time at which the information in the object was created or last modified.
DecryptionCertificateInfo | Contains information about the certificate that decrypts the input document.
ExpectReceiptTimeout | Contains the time, in minutes, in which to expect the receipt for the current document before treating the document as expired.
Expression | Contains a complete set of equations that filter the selection of the object.
Handle | Contains the identifier of the object.
InputDocument | Contains the handle to the input IBizTalkDocument object that describes the input document specification.
IsReceiptChannel | Contains the flag that indicates whether the object is a receipt channel.
LoggingInfo | Contains information about logging the document.
MapContent | Contains the contents of the map that provide instructions on how the input document in the format used by the source organization is to be rendered in the format used by the destination organization, if different.
MapReference | Contains the full Web Distributed Authoring and Versioning (WebDAV) URL of the map that provides instructions on how the input document in the format used by the source organization is to be rendered in the format used by the destination organization, if different.
Name | Contains the name of the object.
OutputDocument | Contains the handle to the output IBizTalkDocument object that describes the output document specification.
Port | Contains the handle to the associated IBizTalkPort object.
PortGroup | Contains the handle to the associated IBizTalkPortGroup object.
ReceiptChannel | Contains the handle to the receipt channel for this object.
RetryCount | Contains the number of times to retry submitting a document when a destination connection failure occurs.
RetryInterval | Contains the amount of time, in minutes, between retry attempts when a destination connection failure occurs during document submission.
SignatureCertificateInfo | Contains information about the certificate that signs the output document.
SourceEndpoint | Contains information about the source.
TrackFields | Contains the IDictionary object that points to the specification that contains fields to track interchange data on input documents for this IBizTalkChannel object.
VerifySignatureCertificateInfo | Contains information about the certificate that verifies the signature of the input document.

IBizTalkChannel defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
GetConfigComponent | Retrieves the CLSID of the component associated with the IBizTalkPort object.
GetConfigData | Retrieves the configuration associated with the specified IBizTalkPort object.
Load | Loads an object in memory.
LoadByName | Loads an object by name in memory.
Remove | Removes the object from the database.
Save | Saves the object in the database.
SetConfigComponent | Sets the CLSID of the component associated with the IBizTalkPort object.
SetConfigData | Sets the configuration information for the associated IBizTalkPort object.

Remarks

An IBizTalkChannel object requires an associated complete IBizTalkPort object. One or more IBizTalkChannel objects can be associated with an IBizTalkPort object. An IBizTalkChannel object can be associated with only one input IBizTalkDocument object and one output IBizTalkDocument object; however, an IBizTalkDocument object can be associated with more than one IBizTalkChannel object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Channels

Document Processing


Comments Property

Contains the user comments for the object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property Comments As String

[C++]

HRESULT get_Comments(

BSTR* Comments

);

HRESULT put_Comments(

BSTR Comments

);

Parameters

Comments

[out, retval], [in] In C++, contains the user comments for the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the user comments for the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string ("").

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


ControlNumberValue Property

Contains the value of the group control number.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property ControlNumberValue As String

[C++]

HRESULT get_ControlNumberValue(

BSTR* strControlNumberValue

);

HRESULT put_ControlNumberValue(

BSTR strControlNumberValue

);

Parameters

strControlNumberValue

[out, retval], [in] In C++, contains the value of the group control number. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the value of the group control number.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The ControlNumberValue property must contain a value between 1 and 999999999.

If the Format property of the IBizTalkEnvelope object for the associated IBizTalkPort object is set to X12, EDIFACT, or Custom, this property is required.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


DecryptionCertificateInfo Property

Contains information about the certificate that decrypts the input document.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property DecryptionCertificateInfo As Object

[C++]

HRESULT get_DecryptionCertificateInfo(

IDispatch** DecryptionCertificateInfoDisp

);

HRESULT putref_DecryptionCertificateInfo(

IDispatch* DecryptionCertificateInfoDisp

);

Parameters

DecryptionCertificateInfoDisp

[out, retval], [in] In C++, contains the information about the certificate that decrypts the input document. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the information about the certificate that decrypts the input document.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information contained by this property includes the Name, Reference, Store, and Usage properties and is created and stored in memory in the IBizTalkCertificateInfo object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


ExpectReceiptTimeout Property

Contains the time, in minutes, in which to expect the receipt for the current document before treating the document as expired.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property ExpectReceiptTimeout As Long

[C++]

HRESULT get_ExpectReceiptTimeout(

long* Minutes

);

HRESULT put_ExpectReceiptTimeout(

long Minutes

);

Parameters

Minutes

[out, retval], [in] In C++, contains the time, in minutes, in which to expect the receipt for the current document before treating the document as expired. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the time, in minutes, in which to expect the receipt for the current document before treating the document as expired.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of 0.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Expression Property

Contains a complete set of equations that filter the selection of the object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property Expression As String

[C++]

HRESULT get_Expression(

BSTR* Expression

);

HRESULT put_Expression(

BSTR Expression

);

Parameters

Expression

[out, retval], [in] In C++, contains a complete set of equations that filter the selection of the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a complete set of equations that filter the selection of the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string (""). If the expression evaluates to true, the server selects the channel for processing the document.

The XPath expression must be based on the input document specification set in the InputDocument property.

Note

  • If the specification field that you are using to create an expression has a Boolean data type, you cannot use the text strings "true" or "false" as the expression value. You must use a numerical value instead: "-1" for true and "0" for false. For example, to filter a channel so it processes only approved purchase orders, your expression might look like this:

Channel1.Expression = "/PORequest/Total[IsApproved = -1]"

This sample assumes that the input document specification contains a Total subelement with a Boolean IsApproved field.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Channel Filtering


GetConfigComponent Method

Retrieves the CLSID of the component associated with the IBizTalkPort object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Method Declaration

[Visual Basic]

Function GetConfigComponent( _

ConfigType As BIZTALK_CONFIGDATA_TYPE, _

PortHandle As Long _

) As String

[C++]

HRESULT GetConfigComponent(

BIZTALK_CONFIGDATA_TYPE ConfigType,

long PortHandle,

BSTR* CLSID

);

Parameters

ConfigType

[in] Determines the configuration type. Valid values for this parameter are defined by the BIZTALK_CONFIGDATA_TYPE enumeration.

PortHandle

[in] Contains the handle to the IBizTalkPort object.

CLSID

[out, retval] In C++, contains the CLSID of the component associated with the IBizTalkPort object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the CLSID of the component associated with the IBizTalkPort object.

In C++, this method returns an HRESULT value, indicating success or failure.

Note

In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

If the ConfigType parameter is set to BIZTALK_CONFIGDATA_TYPE_SIGNATURE and the associated IBizTalkPort object has both the EncryptionType and SignatureType properties set to S/MIME, this method returns an empty string ("").

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


GetConfigData Method

Retrieves the configuration associated with the specified IBizTalkPort object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Method Declaration

[Visual Basic]

Function GetConfigData( _

ConfigType As BIZTALK_CONFIGDATA_TYPE, _

PortHandle As Long, _

Type As Variant _

)

[C++]

HRESULT GetConfigData(

BIZTALK_CONFIGDATA_TYPE ConfigType,

long PortHandle,

VARIANT* Type,

VARIANT* Dictionary

);

Parameters

ConfigType

[in] Determines the configuration type. Valid values for this parameter are defined by the BIZTALK_CONFIGDATA_TYPE enumeration.

PortHandle

[in] Identifies the handle to the associated IBizTalkPort object.

Type

[in, out] Contains the transport type.

Dictionary

[in, out] In C++, contains the IDictionary interface of an object that contains the primary transport configuration information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns an IDictionary object that contains the primary transport configuration information.

In C++, this method returns an HRESULT value, indicating success or failure.

Note

In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

When reading serializer data, the IDictionary object returned by this method has specific string qualifiers used for EDIFACT and X12. The following tables describe these strings.

EDIFACT

Qualifier string | Description
SerializerEdifact_SenderIntID | Interchange sender internal identification
SerializerEdifact_SenderIntSubID | Interchange sender internal subidentification
SerializerEdifact_RecipientIntID | Interchange recipient internal identification
SerializerEdifact_RecipientIntSubID | Interchange recipient internal subidentification
SerializerEdifact_RecipientRefPwd | Recipient reference/password
SerializerEdifact_RecipientRefPwdQual | Recipient reference/password qualifier
SerializerEdifact_ApplicationRef | Application reference
SerializerEdifact_ProcPriCode | Processing priority code
SerializerEdifact_AckRequest | Acknowledgment request
SerializerEdifact_AgreementID | Interchange agreement identifier
SerializerEdifact_TestInd | Test indicator
SerializerEdifact_UNACtrl | "Send UNA Always" or "Send UNA Only When Required"
SerializerEdifact_SyntaxID | Syntax identifier

X12

Qualifier string | Description
SerializerX12_AuthInfoQual | Authorization information qualifier
SerializerX12_AuthInfo | Authorization information
SerializerX12_SecInfoQual | Security information qualifier
SerializerX12_SecInfo | Security information
SerializerX12_CtrlStdID | Interchange control standards identifier
SerializerX12_CtrlVerNum | Interchange control version number
SerializerX12_AckRequired | Acknowledgment required
SerializerX12_UseInd | Usage indicator

Note

  • For more information about the EDIFACT standard, see the United Nations Economic Commission for Europe Web site (www.unece.org).

  • For more information about the X12 standard, see the Data Interchange Standards Association Web site (www.disa.org).

If you override the transport properties of an IBizTalkPort object with this method and then change the transport properties in that IBizTalkPort object, you must call this method again.

If the ConfigType parameter is set to BIZTALK_CONFIGDATA_TYPE_SIGNATURE and the associated IBizTalkPort object has both the EncryptionType and SignatureType properties set to S/MIME, this method returns an empty IDictionary object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


InputDocument Property

Contains the handle to the input IBizTalkDocument object that describes the input document specification.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property InputDocument As Long

[C++]

HRESULT get_InputDocument(

long* InDocHandle

);

HRESULT put_InputDocument(

long InDocHandle

);

Parameters

InDocHandle

[out, retval], [in] In C++, contains the handle of the input IBizTalkDocument object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle of the input IBizTalkDocument object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property.

This property cannot be changed after the Create or the Save method is called.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Configuring

Document Definitions

Document Processing


IsReceiptChannel Property

Contains a flag that indicates whether the object is a receipt channel.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property IsReceiptChannel As Boolean

[C++]

HRESULT get_IsReceiptChannel(

VARIANT_BOOL* IsReceiptChannel

);

HRESULT put_IsReceiptChannel(

VARIANT_BOOL IsReceiptChannel

);

Parameters

IsReceiptChannel

[out, retval], [in] In C++, contains a value indicating whether or not the channel is a receipt channel. VARIANT_TRUE indicates that this channel is a receipt channel; VARIANT_FALSE indicates that this channel is not a receipt channel. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value indicating whether or not the channel is a receipt channel. True indicates that this channel is a receipt channel; False indicates that this channel is not a receipt channel.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

ReceiptChannel


LoggingInfo Property

Contains information about logging the document.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property LoggingInfo As Object

[C++]

HRESULT get_LoggingInfo(

IDispatch** LoggingInfoDisp

);

HRESULT putref_LoggingInfo(

IDispatch* LoggingInfoDisp

);

Parameters

LoggingInfoDisp

[out, retval], [in] In C++, contains the logging fields. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the logging fields.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Information contained by this property includes the LogNativeInputDocument, LogNativeOutputDocument, LogXMLInputDocument, and LogXMLOutputDocument properties and is created and stored in memory in the IBizTalkLoggingInfo object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


MapContent Property

Contains the contents of the map that provide instructions on how the input document in the format used by the source organization is to be rendered in the format used by the destination organization, if different.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property MapContent As String

[C++]

HRESULT get_MapContent(

BSTR* MapContent

);

onkeypress="expand(expand3, img3)" onclick="expand(expand3, img3)"> Parameters

MapContent

[in] In C++, contains the map contents. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the map contents.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string (""). This is a read-only property. The Create and Save methods copy the text of the map specified by the MapReference property to this string, if empty.

Once you have created or saved a IBizTalkChannel object with MapReference set to a map, any changes you make to the content of the referenced map are not automatically updated on the referring IBizTalkChannel object. To update the IBizTalkChannel object that refers to the revised map, you must save the map, reset the MapReference property of the IBizTalkChannel object to its current value, and then call Save on the referring IBizTalkChannel object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


MapReference Property

Contains the full Web Distributed Authoring and Versioning (WebDAV) URL of the map that provides instructions on how the input document in the format used by the source organization is to be rendered in the format used by the destination organization, if different.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property MapReference As String

[C++]

HRESULT get_MapReference(

BSTR* Reference

);

HRESULT put_MapReference(

BSTR Reference

);

Parameters

Reference

[out, retval], [in] In C++, contains the map name. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the map name.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string (""). This is a required property if the InputDocument property refers to a different document specification than the OutputDocument property.

Once you have created or saved a IBizTalkChannel object with MapReference set to a map, any changes you make to the content of the referenced map are not automatically updated on the referring IBizTalkChannel object. To update the IBizTalkChannel object that refers to the revised map, you must save the map, reset the MapReference property of the IBizTalkChannel object to its current value, and then call Save on the referring IBizTalkChannel object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


OutputDocument Property

Contains the handle to the IBizTalkDocument object that describes the output document specification.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property OutputDocument As Long

[C++]

HRESULT get_OutputDocument(

long* OutDocHandle

);

HRESULT put_OutputDocument(

long OutDocHandle

);

Parameters

OutDocHandle

[out, retval], [in] In C++, contains the handle to the output IBizTalkDocument object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the output IBizTalkDocument object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property. This property cannot be changed after the Create or the Save method is called.

If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_SOURCE, the InputDocument property can identify an input IBizTalkDocument object that has an X12 or an EDIFACT specification. If it does, however, OutputDocument must not identify an IBizTalkDocument object that has an X12 or an EDIFACT specification.

If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_DESTINATION, the OutputDocument property for this IBizTalkChannel object must not identify an output IBizTalkDocument object that has an X12 or an EDIFACT specification.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Definitions


Port Property

Contains the handle to the associated IBizTalkPort object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property Port As Long

[C++]

HRESULT get_Port(

long* PortHandle

);

HRESULT put_Port(

long PortHandle

);

Parameters

PortHandle

[out, retval], [in] In C++, contains the handle to the IBizTalkPort object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the IBizTalkPort object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The following constraints are enforced:

  • Either the Port or the PortGroup property must be specified for a channel.

  • This property cannot be changed after the Create or the Save method is called.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Messaging Ports


PortGroup Property

Contains the handle to the associated IBizTalkPortGroup object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property PortGroup As Long

[C++]

HRESULT get_PortGroup(

long* PortGroupHandle

);

HRESULT put_PortGroup(

long PortGroupHandle

);

Parameters

PortGroupHandle

[out, retval], [in] In C++, contains the handle to the associated IBizTalkPortGroup object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the associated IBizTalkPortGroup object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The following constraints are enforced:

  • Either the Port property or PortGroup must be specified for a channel.

  • This property cannot be changed after the Create or the Save method is called.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Port Groups


ReceiptChannel Property

Contains the handle to the receipt channel for this object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property ReceiptChannel As Long

[C++]

HRESULT get_ReceiptChannel(

long* ReceiptChannelHandle

);

HRESULT put_ReceiptChannel(

long ReceiptChannelHandle

);

Parameters

ReceiptChannelHandle

[out, retval], [in] In C++, contains the handle to the receipt channel. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the receipt channel.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. An IBizTalkChannel object can specify a receipt channel only if it is not a receipt channel itself. The channel specified as the receipt channel must have the IsReceiptChannel property set to TRUE. In addition, the receipt channel must use a messaging port with a DestinationEndpoint that is the same as the SourceEndpoint on the channel using the receipt channel. This allows the receipt channel to send a receipt to the original source of the document.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


RetryCount Property

Contains the number of times to retry submitting a document when a destination connection failure occurs.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property RetryCount As Long

[C++]

HRESULT get_RetryCount(

long* Count

);

HRESULT put_RetryCount(

long Count

);

Parameters

Count

[out, retval], [in] In C++, contains the number of retries. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of retries.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The RetryCount property must contain a value between 0 and 999. The default value is 3 retries.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


RetryInterval Property

Contains the amount of time, in minutes, between retry attempts when a destination connection failure occurs during document submission.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property RetryInterval As Long

[C++]

HRESULT get_RetryInterval(

long* Interval

);

HRESULT put_RetryInterval(

long Interval

);

Parameters

Interval

[out, retval], [in] In C++, contains the retry interval, in minutes. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the retry interval, in minutes.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The RetryInterval property must contain a value between 1 and 63999. The default value is 5 minutes.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SetConfigComponent Method

Sets the CLSID of the component associated with the IBizTalkPort object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Method Declaration

[Visual Basic]

Sub SetConfigComponent( _

ConfigType As BIZTALK_CONFIGDATA_TYPE, _

PortHandle As Long, _

CLSID As String _

)

[C++]

HRESULT SetConfigComponent(

BIZTALK_CONFIGDATA_TYPE ConfigType,

long PortHandle,

BSTR CLSID

);

Parameters

ConfigType

[in] Determines the configuration type. Valid values for this parameter are defined by the BIZTALK_CONFIGDATA_TYPE enumeration.

PortHandle

[in] Contains the handle.

CLSID

[in] Contains the CLSID of the component.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SetConfigData Method

Sets the configuration information for the associated IBizTalkPort object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Method Declaration

[Visual Basic]

Sub SetConfigData( _

ConfigType As BIZTALK_CONFIGDATA_TYPE, _

ConfigDataHandle As Long, _

ConfigDataDisp As Object _

)

[C++]

HRESULT SetConfigData(

BIZTALK_CONFIGDATA_TYPE ConfigType,

long ConfigDataHandle,

IDispatch* ConfigDataDisp

);

Parameters

ConfigType

[in] Determines the configuration type. Valid values for this parameter are defined by the BIZTALK_CONFIGDATA_TYPE enumeration.

ConfigDataHandle

[in] Identifies the handle to the associated IBizTalkPort object.

ConfigDataDisp

[in] IDictionary object that contains information about the component specified in the ConfigType parameter.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The IDictionary object passed to this method has specific string qualifiers used for EDIFACT and X12. For a description of these qualifiers, see the GetConfigData Method.

When using the BIZTALK_CONFIGDATA_TYPE_PRIMARYTRANSPORT or BIZTALK_CONFIGDATA_TYPE_SECONDARYTRANSPORT enumeration value, the content of the transport dictionary varies according to the transport protocol used. The following tables list the transport dictionary fields for each protocol.

HTTP and HTTPS

Field name | Data type | Required | Description
URL | String | Yes | URL of the document destination.
ContentType | String | No | Value for the Content-Type HTTP/HTTPS property that appears in HTTP headers during transmission. The default value is an empty string ("").
ClientCert | String | No | Reference to the certificate used with SSL connections using HTTPS. The default value is an empty string ("").
ProxyName | String | No | URL of the proxy server used when sending documents outside a firewall.
ProxyPort | Integer | No | Port number used by the proxy server.
UseProxy | Boolean | No | Value that indicates whether the proxy server is used. The default value is True.

Local File

Field name | Data type | Required | Description
Filename | String | Yes | Name and path of the file to be created.
CopyMode | Integer | No | Value that indicates how the file should be written. Use a value of 0 for overwrite mode, a value of 1 for append mode, and a value of 2 to create a new file. The default value is append mode (1).
UserName | String | No | Windows NT username needed to access a file share. The default value is an empty string ("").
Password | String | No | Windows NT username needed to access a file share. The default value is an empty string ("").

Message Queuing

Field name | Data type | Required | Description
QueueName | String | Yes | Name of the Messaging Queue to which the document is sent.
MessageLabel | String | Yes | Value specified in the message label field on the queue.
Priority | Integer | No | Priority of the message placed in the queue. This must be a value between 0 and 7, where a higher value indicates a higher priority. The default value is 3
AuthLevel | Integer | No | Value indicating whether the message needs to be authenticated using a digital signature. Use a value of 0 to bypass authentication. A value of 1 indicates that authentication will be used. The default value is 0.
Delivery | Integer | No | Value indicating how a message is delivered to a queue. Use a value of 1 to indicate that the message should be backed up until it is delivered to the queue. A value of 0 indicates that the message is only resident in memory. The default value is 0.

Notes

  • When you override messaging port properties in a channel, the overrides apply only to that channel. No errors are generated as a result of overriding previous values.

  • You cannot override the transport address that was set in a messaging port.

  • The default setting for the HTTP transport component is to use the HTTP proxy server. This is the correct setting to transport data to Web sites outside your business's firewall. To transport data to Web sites that are inside your business's firewall (that is, within your intranet), modify the transport dictionary values to override the default setting.

  • For the HTTPS transport component, use only certificates that are specified for client authentication.

  • The default setting for the file transport component is to append files (CopyMode=1). If you choose the file transport type with its default settings in a messaging port and use antivirus software on the server on which BizTalk Server 2002 is installed, and you send multiple files that have exactly the same name to the same file location, at the same time, BizTalk Server 2002 might stop responding and must be restarted. You can eliminate this problem by changing the default setting for the file transport component to overwrite (CopyMode=0). You also can eliminate this problem by creating a unique file for each document instance processed by using %tracking_id% in the Address property of the IBizTalkTransportInfo object.

To access the properties in a custom component dictionary through BizTalk Messaging Manager, you must create ASP pages in the \Program Files\BizTalk Server\MessagingManager\pipeline folder. These ASP pages provide a dialog box for editing the properties of your custom component. This dialog box is displayed from the channel Advanced Configuration page when you click Advanced and then click Properties on the Primary Transport tab. For additional information about the ASP pages, see Working with Serializers. For a sample that uses SetConfigData with custom property pages, see Synchronous Orchestration Component.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SignatureCertificateInfo Property

Contains information about the certificate that signs the output document.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property SignatureCertificateInfo As Object

[C++]

HRESULT get_SignatureCertificateInfo(

IDispatch** SignatureCertificateInfoDisp

);

HRESULT putref_SignatureCertificateInfo(

IDispatch* SignatureCertificateInfoDisp

);

Parameters

SignatureCertificateInfoDisp

[out, retval], [in] In C++, contains the certificate information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the certificate information.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information contained by this property includes the Name, Reference, Store, and Usage properties and is created and stored in memory in the BizTalkCertificateInfo object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SourceEndpoint Property

Contains information about the source.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property SourceEndpoint As Object

[C++]

HRESULT get_SourceEndpoint(

IDispatch** SrcEndpointDisp

);

HRESULT putref_SourceEndpoint(

IDispatch* SrcEndpointDisp

);

Parameters

SrcEndpointDisp

[out, retval], [in] In C++, contains information about the source. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns information about the source.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information contained by this property includes the Alias, Application, and Organization properties and is created and stored in memory in the IBizTalkEndPoint object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


TrackFields Property

Contains the IDictionary object that points to the specification that contains fields to track interchange data on input documents for this BizTalkChannel object.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property TrackFields As Object

[C++]

HRESULT get_TrackFields(

IDispatch** TrackFieldsDisp

);

HRESULT putref_TrackFields(

IDispatch* TrackFieldsDisp

);

Parameters

TrackFieldsDisp

[out, retval], [in] In C++, contains the custom tracking fields. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the custom tracking fields.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The tracking fields specified by this property override the fields set in the TrackFields property on the IBizTalkDocument object.

The fields in the IDictionary object must contain an XPath value that identifies the field to be tracked in a document. By default, the IDictionary object provides eight predefined fields for tracking data in a document. These predefined fields consist of two fields for each of the following data types: integer, real, date, and string. If additional fields are required for tracking, you can use the x_custom_search field in the IDictionary object, and set the value to an ISimpleList object. The ISimpleList object contains a list of XPaths pointing to the additional tracking fields. XPath values can be added to and deleted from this list using the Add and Delete methods.

The following table shows the field names in the IDictionary object for TrackFields:

Field Name | Field type
i_value1 | Integer value
i_value2 | Integer value
r_value1 | Real value
r_value2 | Real value
d_value1 | Date value
d_value2 | Date value
s_value1 | String value
s_value2 | String value
x_custom_search | A list to return one or more additional data items

For more information about XPath expressions, go to the Microsoft Web site (msdn.microsoft.com/library/default.asp) and search for XPath.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Tracking


VerifySignatureCertificateInfo Property

Contains information about the certificate that verifies the signature of the input document.

Member List

IBizTalkChannel

|--Comments

|--ControlNumberValue

|--DecryptionCertificateInfo

|--ExpectReceiptTimeout

|--Expression

|--GetConfigComponent

|--GetConfigData

|--InputDocument

|--IsReceiptChannel

|--LoggingInfo

|--MapContent

|--MapReference

|--OutputDocument

|--Port

|--PortGroup

|--ReceiptChannel

|--RetryCount

|--RetryInterval

|--SetConfigComponent

|--SetConfigData

|--SignatureCertificateInfo

|--SourceEndpoint

|--TrackFields

|--VerifySignatureCertificateInfo

Property Declaration

[Visual Basic]

Property VerifySignatureCertificateInfo As Object

[C++]

HRESULT get_VerifySignatureCertificateInfo(

IDispatch** VerifySignatureCertificateInfoDisp

);

HRESULT putref_VerifySignatureCertificateInfo(

IDispatch* VerifySignatureCertificateInfoDisp

);

Parameters

VerifySignatureCertificateInfoDisp

[out, retval], [in] In C++, contains the certificate information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the certificate information.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information contained by this property includes the Name, Reference, Store, and Usage properties and is created and stored in memory in the IBizTalkCertificateInfo object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkConfig

Creates channels, document specifications, envelopes, organizations, ports, and port groups.

Hierarchy

IDispatch

|--IBizTalkConfig

Declaration

[Visual Basic]

Class BizTalkConfig

[C++]

interface IBizTalkConfig : IDispatch

Members

IBizTalkConfig defines the following properties:

Property | Description
Certificates | Contains an ADO recordset that contains all specified certificates.
Channels | Contains an ADO recordset that contains all IBizTalkChannel objects.
Documents | Contains an ADO recordset that contains all IBizTalkDocument objects.
Envelopes | Contains an ADO recordset that contains all IBizTalkEnvelope objects.
Organizations | Contains an ADO recordset that contains all IBizTalkOrganization objects.
PortGroups | Contains an ADO recordset that contains all IBizTalkPortGroup objects.
Ports | Contains an ADO recordset that contains all IBizTalkPort objects.

IBizTalkConfig defines the following methods:

Method | Description
CreateChannel | Returns a new IBizTalkChannel object.
CreateDocument | Returns a new IBizTalkDocument object.
CreateEnvelope | Returns a new IBizTalkEnvelope object.
CreateOrganization | Returns a new IBizTalkOrganization object.
CreatePort | Returns a new IBizTalkPort object.
CreatePortGroup | Returns a new IBizTalkPortGroup object.

Remarks

Each object created by using one of the methods of this interface inherits the following common methods from IBizTalkBase:

  • DateModified

  • Handle

  • Name

  • Clear

  • Create

  • Load

  • LoadByName

  • Remove

  • Save

When IBizTalkPort and IBizTalkChannel objects are created, BizTalk Server automatically creates some associated subobjects. You can access these subobjects by using properties of the IBizTalkPort and IBizTalkChannel objects.

The relationship between objects, their subobjects, and the properties used to obtain the subobjects is shown in the following table.

Subobject | Associated object | Property to set
BizTalkEndPoint | BizTalkPort | DestinationEndpoint
BizTalkEndPoint | BizTalkChannel | SourceEndpoint
BizTalkLoggingInfo | BizTalkChannel | LoggingInfo
BizTalkTransportInfo | BizTalkPort | PrimaryTransport, SecondaryTransport
BizTalkServiceWindowInfo | BizTalkPort | ServiceWindowInfo
BizTalkCertificateInfo | BizTalkPort | EncryptionCertificateInfo
BizTalkCertificateInfo | BizTalkChannel | SignatureCertificateInfo, VerifySignatureCertificateInfo, or DecryptionCertificateInfo

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Certificates Property

Contains an ADO recordset that contains all specified certificates.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Certificates( _

StoreType As BIZTALK_STORE_TYPE, _

UsageType As BIZTALK_USAGE_TYPE, _

NamePrefix As String _

) As Object

[C++]

HRESULT get_Certificates(

BIZTALK_STORE_TYPE StoreType,

BIZTALK_USAGE_TYPE UsageType,

BSTR NamePrefix,

IDispatch** CertsDisp

);

Parameters

StoreType

[in] Determines the store type. Valid values for this parameter are defined by the BIZTALK_STORE_TYPE enumeration.

UsageType

[in] Determines the usage type. Valid values for this parameter are defined by the BIZTALK_USAGE_TYPE enumeration.

NamePrefix

[in] Contains a prefix used as the selection criteria for certificate names. Any certificate Name starting with this value is returned in the recordset. This value is case sensitive.

CertsDisp

[out, retval] Contains all specified certificates. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all specified certificates.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkCertificateInfo object in the database. The fields in each record contain the following information:

Field content | Item number
Name | 0
Reference | 1
Store | 2
Usage | 3

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


Channels Property

Contains an ADO recordset that contains all IBizTalkChannel objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Channels As Object

[C++]

HRESULT get_Channels(

IDispatch** ChannelsDisp

);

Parameters

ChannelsDisp

[out, retval] Contains all IBizTalkChannel objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all IBizTalkChannel objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkChannel object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


CreateChannel Method

Returns a new IBizTalkChannel object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreateChannel( ) As Object

[C++]

HRESULT CreateChannel(

IDispatch** ChannelDisp

);

Parameters

ChannelDisp

[out, retval] Contains a new IBizTalkChannel object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkChannel object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreateDocument Method

Returns a new IBizTalkDocument object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreateDocument( ) As Object

[C++]

HRESULT CreateDocument(

IDispatch** DocumentDisp

);

Parameters

DocumentDisp

[out, retval] Contains a new IBizTalkDocument object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkDocument object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreateEnvelope Method

Returns a new IBizTalkEnvelope object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreateEnvelope( ) As Object

[C++]

HRESULT CreateEnvelope(

IDispatch** EnvelopeDisp

);

Parameters

EnvelopeDisp

[out, retval] Contains a new IBizTalkEnvelope object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkEnvelope object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreateOrganization Method

Returns a new IBizTalkOrganization object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreateOrganization( ) As Object

[C++]

HRESULT CreateOrganization(

IDispatch** OrganizationDisp

);

Parameters

OrganizationDisp

[out, retval] Contains a new IBizTalkOrganization object. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkOrganization object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreatePort Method

Returns a new IBizTalkPort object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreatePort( ) As Object

[C++]

HRESULT CreatePort(

IDispatch** PortDisp

);

Parameters

PortDisp

[out, retval] Contains a new IBizTalkPort object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkPort object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreatePortGroup Method

Returns a new IBizTalkPortGroup object.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Method Declaration

[Visual Basic]

Function CreatePortGroup( ) As Object

[C++]

HRESULT CreatePortGroup(

IDispatch** PortGroupDisp

);

Parameters

PortGroupDisp

[out, retval] Contains a new IBizTalkPortGroup object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a new IBizTalkPortGroup object.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Documents Property

Contains an ADO recordset that contains all IBizTalkDocument objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Documents( ) As Objects

[C++]

HRESULT get_Documents(

IDispatch** DocumentsDisp

);

Parameters

DocumentsDisp

[out, retval] Contains all BizTalkDocument objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all BizTalkDocument objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkDocument object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


Envelopes Property

Contains an ADO recordset that contains all IBizTalkEnvelope objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Envelopes( ) As Objects

[C++]

HRESULT get_Envelopes(

IDispatch** EnvelopesDisp

);

Parameters

EnvelopesDisp

[out, retval] Contains all IBizTalkEnvelope objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all IBizTalkEnvelope objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkEnvelope object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2
Format | 3

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


Organizations Property

Contains an ADO recordset that contains all IBizTalkOrganization objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Organizations( ) As Objects

[C++]

HRESULT get_Organizations(

IDispatch** OrganizationsDisp

);

Parameters

OrganizationsDisp

[out, retval] Contains all IBizTalkOrganization objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all IBizTalkOrganization objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkOrganization object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2
IsDefault | 3

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


PortGroups Property

Contains an ADO recordset that contains all IBizTalkPortGroup objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property PortGroups( ) As Objects

[C++]

HRESULT get_PortGroups(

IDispatch** PortGroupsDisp

);

Parameters

PortGroupsDisp

[out, retval] Contains all IBizTalkPortGroup objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all IBizTalkPortGroup objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkPortGroup object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


Ports Property

Contains an ADO recordset that contains all IBizTalkPort objects.

Member List

IBizTalkConfig

|--Certificates

|--Channels

|--CreateChannel

|--CreateDocument

|--CreateEnvelope

|--CreateOrganization

|--CreatePort

|--CreatePortGroup

|--Documents

|--Envelopes

|--Organizations

|--PortGroups

|--Ports

Property Declaration

[Visual Basic]

Property Ports( ) As Objects

[C++]

HRESULT get_Ports(

IDispatch** PortsDisp

);

Parameters

PortsDisp

[out, retval] Contains all IBizTalkPort objects. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all IBizTalkPort objects.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about an existing IBizTalkPort object in the database. The fields in each record contain the following information:

Field content | Item number
Handle | 0
Name | 1
DateModified | 2

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Update Messaging Configurations with ADO Objects


IBizTalkDocument

Identifies and describes the document specification of a document.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkDocument

Declaration

[Visual Basic]

Class BizTalkDocument

[C++]

interface IBizTalkDocument : IBizTalkBase

Members

IBizTalkDocument defines the following properties:

Property | Description
Content | Contains the content of the document specification described by the object.
DateModified | Contains the date and time at which the information in the object was created or last modified.
Handle | Contains the handle to the object.
Name | Contains the name of the object.
NameSpace | Contains the string that resolves naming conflicts between elements in a document.
PropertySet | Contains an IDictionary object that contains the electronic data interchange (EDI) selection criteria (name/value pairs) by which the server extracts information from the functional group header of the EDI document to identify the object when the document is input.
Reference | Contains the full Web Distributed Authoring and Versioning (WebDAV) URL for the document specification referred to by this IBizTalkDocument object.
TrackFields | Contains an IDictionary object that stores the custom fields that Tracking uses to track all documents processed by the server, based on this document instance.
Type | Contains the type of document specification.
Version | Contains the version of the document standard.

IBizTalkDocument defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
Load | Loads a specified object in memory.
LoadByName | Loads a specified object by name in memory.
LoadByPropertySet | Loads the document object by its PropertySet object.
Remove | Removes the object from the database.
Save | Saves the object in the database.

Remarks

Each IBizTalkDocument object must have at least one associated IBizTalkChannel object. More than one IBizTalkDocument object can refer to the same document specification.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Definitions


Content Property

Contains the content of the document specification described by the object.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property Content As String

[C++]

HRESULT get_Content(

BSTR* Content

);

Parameters

Content

[out, retval] In C++, contains the content. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the content.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with a default value of an empty string ("").

The Reference property is checked when the Create or the Save method is called. If this string is not empty when Create is called, Content is set to the contents of the document specification and the NameSpace property is changed to the value found in the document specification.

Once you have created or saved an object with Reference set to a document specification, any changes you make to the Content or NameSpace of the referenced document specification are not automatically updated on the referring object. To update the object that refers to the revised document specification, you must save the document specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


LoadByPropertySet Method

Loads the document object by its PropertySet object.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Method Declaration

[Visual Basic]

Property LoadByPropertySet( _

PropSetDictionaryDisp As Object _

)

[C++]

HRESULT LoadByPropertySet(

IDispatch** PropSetDictionaryDisp

);

Parameters

PropSetDictionaryDisp

[in] In C++, contains the PropertySet. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the PropertySet.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


NameSpace Property

Contains the string that resolves naming conflicts between elements in a document.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property NameSpace As String

[C++]

HRESULT get_NameSpace(

BSTR* NameSpace

);

Parameters

NameSpace

[out, retval] In C++, contains the namespace. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the namespace.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with a default value of an empty string ("").

The Reference property is checked when the Create or the Save method is called. If this string is not empty when Create is called, Content is set to the contents of the document specification and NameSpace is changed to the value found in the document specification.

Once you have created or saved an object with Reference set to a document specification, any changes you make to the Content or NameSpace of the referenced document specification are not automatically updated on the referring object. To update the object that refers to the revised document specification, you must save the document specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

Note

  • When creating a document, the number of characters in the NameSpace combined with the number of characters in the specification name cannot exceed 255.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


PropertySet Property

Contains an IDictionary object that contains the electronic data interchange (EDI) selection criteria (name/value pairs) by which the server extracts information from the functional group header of the EDI document to identify the object when the document is input.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property PropertySet As Object

[C++]

HRESULT get_PropertySet(

IDispatch** PropSetDisp

);

HRESULT putref_PropertySet(

IDispatch* PropSetDisp

);

Parameters

PropSetDisp

[out, retval], [in] In C++, contains the selection criteria. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the selection criteria.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value.

This is a required property if the document is an EDI document. The Delimiters property of the associated IBizTalkPort object must also be defined.

The following table shows whether names are required in the IDictionary object for PropertySet.

Selection criteria | X12 | EDIFACT
application_sender_code | Yes | Yes
application_receiver_code | Yes | Yes
functional_identifier | Yes | Yes
standards_version | Yes | No
standards_version_type | No | Yes
standards_version_value | No | Yes

Note

  • The name/value pairs contained in the IDictionary object cannot exceed a total of 450 bytes.

PropertySet can be set only if the Reference property is set.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Definitions


Reference Property

Contains the full Web Distributed Authoring and Versioning (WebDAV) URL for the document specification referred to by this IBizTalkDocument object.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property Reference As String

[C++]

HRESULT get_Reference(

BSTR* Reference

);

HRESULT put_Reference(

BSTR Reference

);

Parameters

Reference

[out, retval], [in] In C++, contains the reference. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the reference.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string ("").

Reference is checked when the Create or the Save method is called. If this string is not empty when Create is called, Content is set to the contents of the document specification and the NameSpace property is changed to the value found in the document specification.

Once you have created or saved an object with Reference set to a document specification, any changes you make to the Content or NameSpace of the referenced document specification are not automatically updated on the referring object. To update the object that refers to the revised document specification, you must save the document specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

If Reference is not set, the PropertySet and TrackFields properties must not be set.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


TrackFields Property

Contains an IDictionary object that stores the custom fields that Tracking uses to track all documents processed by the server, based on this document instance.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property TrackFields As Object

[C++]

HRESULT get_TrackFields(

IDispatch** TrackFieldsDisp

);

HRESULT putref_TrackFields(

IDispatch* TrackFieldsDisp

);

Parameters

TrackFieldsDisp

[out, retval], [in] In C++, contains the custom tracking fields. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the custom tracking fields.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value.

TrackFields can be set only if the Reference property is set. Tracking fields specified for an output IBizTalkDocument object are ignored.

An IBizTalkDocument object points to the specification that contains fields to track the document. The designated fields are logged to the Tracking database for each instance of a document that is processed. Tracking fields on the IBizTalkDocument object are global. The TrackFields property on the IBizTalkChannel object overrides the values specified by this property.

The fields in the IDictionary object must contain an XPath value that identifies the field to be tracked in a document. By default, the IDictionary object provides eight predefined fields for tracking data in a document. These predefined fields consist of two fields for each of the following data types: integer, real, date, and string. If additional fields are required for tracking, you can use the x_custom_search field in the IDictionary object and set the value to a SimpleList object. The SimpleList object contains a list of XPaths pointing to the additional tracking fields. XPath values can be added to and deleted from this list using the Add and Delete methods.

The following table shows the field names in the IDictionary object for TrackFields:

Field Name | Field type
i_value1 | Integer value
i_value2 | Integer value
r_value1 | Real value
r_value2 | Real value
d_value1 | Date value
d_value2 | Date value
s_value1 | String value
s_value2 | String value
x_custom_search | A list to return one or more additional data items

For more information about XPath expressions, go to the Microsoft Web site (msdn.microsoft.com/library/default.asp) and search for XPath.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Definitions

Document Tracking


Type Property

Contains the version of the document standard.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property Type As String

[C++]

HRESULT get_Type(

BSTR* Type

);

Parameters

Type

[out, retval] In C++, contains the document type. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the document type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with a default value of an empty string ("").

All document instances must have the same document type as the associated envelope. For example, if the Format property of the IBizTalkEnvelope object is set to X12, Type must also be X12.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Version Property

Contains the version of the document standard.

Member List

IBizTalkDocument

|--Content

|--LoadByPropertySet

|--NameSpace

|--PropertySet

|--Reference

|--TrackFields

|--Type

|--Version

Property Declaration

[Visual Basic]

Property Version As String

[C++]

HRESULT get_Version(

BSTR* Version

);

Parameters

Version

[out, retval] In C++, contains the version. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the version.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkEndPoint

Configures source information for an IBizTalkChannel object and destination information for an IBizTalkPort object.

Hierarchy

IDispatch

|--IBizTalkEndPoint

Declaration

[Visual Basic]

Class BizTalkEndpoint

[C++]

interface IBizTalkEndpoint : IDispatch

Members

IBizTalkEndPoint defines the following properties:

Property | Description
Alias | Contains a handle to the organization identifier type/value pair for the destination IBizTalkOrganization object for the associated IBizTalkPort object.
Application | Contains a handle to the associated application for the destination IBizTalkOrganization object for this IBizTalkPort object.
Openness | Contains an enumeration value that indicates whether the object has an open destination or source, or neither.
Organization | Contains a handle to the destination IBizTalkOrganization object for this IBizTalkPort object.

Remarks

The IBizTalkEndPoint object is automatically created when an IBizTalkPort object or an IBizTalkChannel object is instantiated with the CreatePort or the CreateChannel method of the IBizTalkConfig object.

For destination endpoints, access the IBizTalkEndPoint object by using the DestinationEndpoint property of the IBizTalkPort object. For source endpoints, access the IBizTalkEndPoint object by using the SourceEndpoint property of the IBizTalkChannel object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Alias Property

Contains a handle to the organization identifier type/value pair for the destination IBizTalkOrganization object for the associated IBizTalkPort object.

Member List

IBizTalkEndPoint

|--Alias

|--Application

|--Openness

|--Organization

Property Declaration

[Visual Basic]

Property Alias As Long

[C++]

HRESULT get_Alias(

long* AliasHandle

);

HRESULT put_Alias(

long AliasHandle

);

Parameters

AliasHandle

[out, retval], [in] In C++, contains the handle to the alias. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the alias.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Application Property

Contains a handle to the associated application for the destination IBizTalkOrganization object for this IBizTalkPort object.

Member List

IBizTalkEndPoint

|--Alias

|--Application

|--Openness

|--Organization

Property Declaration

[Visual Basic]

Property Application As Long

[C++]

HRESULT get_Application(

long* AppHandle

);

HRESULT put_Application(

long AppHandle

);

Parameters

AppHandle

[out, retval], [in] In C++, contains the handle to the application. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the application.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Openness Property

Contains an enumeration value that indicates whether the object has an open destination or source, or neither.

Member List

IBizTalkEndPoint

|--Alias

|--Application

|--Openness

|--Organization

Property Declaration

[Visual Basic]

Property Openness As BIZTALK_OPENNESS_TYPE_EX

[C++]

HRESULT get_Openness(

BIZTALK_OPENNESS_TYPE_EX* OpennessType

);

HRESULT put_Openness(

BIZTALK_OPENNESS_TYPE_EX OpennessType

);

Parameters

OpennessType

[out, retval], [in] In C++, contains a value indicating whether the object has an open destination or source, or neither. Valid values for this parameter are defined by the BIZTALK_OPENNESS_TYPE_EX enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_OPENNESS_TYPE_EX enumeration, indicating whether the object has an open destination or source, or neither.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of BIZTALK_OPENNESS_TYPE_EX_NOTOPEN.

The IBizTalkPort object is valid only if the associated document or the parameters on the Submit or the SubmitSync method of IInterchange identify the missing information.

If Openness is set to BIZTALK_OPENNESS_TYPE_EX_SOURCE for an IBizTalkEndPoint object associated with a channel, the following constraints apply:

  • The SignatureType property must not be set.

  • The IBizTalkPort object cannot be included in a port group.

If Openness is set to BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW on a channel, the associated IBizTalkOrganization object must be the default organization.

If Openness on the object is set to BIZTALK_OPENNESS_TYPE_EX_DESTINATION for an IBizTalkEndPoint object associated with a messaging port, the following constraints apply:

  • The PrimaryTransportType property must be set to BIZTALK_TRANSPORT_TYPE_OPENDESTINATION.

  • The EncryptionType property must not be set.

  • The document or the parameters on Submit or SubmitSync must specify the destination, transport type, and address.

  • The IBizTalkPort object cannot be included in a port group.

Note

  • This property cannot be changed on an existing port.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Openness


Organization Property

Contains a handle to the destination IBizTalkOrganization object for this IBizTalkPort object.

Member List

IBizTalkEndPoint

|--Alias

|--Application

|--Openness

|--Organization

Property Declaration

[Visual Basic]

Property Organization As Long

[C++]

HRESULT get_Organization(

long* OrganizationHandle

);

HRESULT put_Organization(

long OrganizationHandle

);

Parameters

OrganizationHandle

[out, retval], [in] In C++, contains the handle to the organization. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the organization.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property for this object to be complete unless the Openness property is set to BIZTALK_OPENNESS_TYPE_EX_DESTINATION.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkEnvelope

Configures the envelope format used with documents processed by BizTalk Server. An envelope is the header information for an interchange.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkEnvelope

Declaration

[Visual Basic]

Class BizTalkEnvelope

[C++]

interface IBizTalkEnvelope : IBizTalkBase

Members

IBizTalkEnvelope defines the following properties:

Property | Description
Content | Contains the contents of the selected envelope format specification.
DateModified | Contains the date and time at which the information in the object was created or last modified.
Format | Contains a string that identifies the type of envelope.
Handle | Contains the handle to the object.
Name | Contains the name of the object.
NameSpace | Contains a string that resolves naming conflicts between elements in an envelope specification.
Reference | Contains a full Web Distributed Authoring and Versioning (WebDAV) URL name of the envelope format specification file.
Version | Contains the version of the envelope format specification.

IBizTalkEnvelope defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
Load | Loads a specified object in memory.
LoadByName | Loads a specified object by name in memory.
Remove | Removes the object from the database.
Save | Saves the object in the database.

Remarks

All document instances in an electronic data interchange (EDI) functional group must have the same format. All document instances must have the same document type as the associated envelope. For example, if Format is set to X12, the Type property of the IBizTalkDocument objects for the associated IBizTalkPort object must also be X12.

If you use an envelope with an EDIFACT format and you want to use a null value for the empty qualifier in the header for the source or the destination, create a custom identifier with a single dash (-) as the qualifier. To do this, use the CreateAlias method on the IBizTalkOrganization object. When an empty qualifier is encountered on an input EDIFACT envelope, the server converts the empty qualifier to a dash. For an output EDIFACT envelope, the server converts the dash to an empty qualifier.

The IBizTalkEnvelope object is required for input documents if the Type property of the IBizTalkDocument object is set to "flatfile" or "custom xml".

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Envelopes


Content Property

Contains the contents of the selected envelope format specification.

Member List

IBizTalkEnvelope

|--Content

|--Format

|--NameSpace

|--Reference

|--Version

Property Declaration

[Visual Basic]

Property Content As String

[C++]

HRESULT get_Content(

BSTR* Content

);

Parameters

Content

[out, retval] In C++, contains the content. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the content.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

The Reference property is checked when the Create or the Save method is called. If this string is not empty when Create is called, Content is set to the contents of the envelope specification, and the NameSpace property is changed to the value found in the envelope specification.

Once you have created or saved an object with Reference set to an envelope specification, any changes you make to the Content or NameSpace of the referenced envelope specification are not automatically updated on the referring object. To update the object that refers to the revised envelope specification, you must save the envelope specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Format Property

Contains a string that identifies the type of envelope.

Member List

IBizTalkEnvelope

|--Content

|--Format

|--NameSpace

|--Reference

|--Version

Property Declaration

[Visual Basic]

Property Format As String

[C++]

HRESULT get_Format(

BSTR* Format

);

HRESULT put_Format(

BSTR Format

);

Parameters

Format

[out, retval], [in] In C++, contains the envelope format. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the envelope format.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The format value must be one of the following strings:

  • x12

  • edifact

  • custom xml (default)

  • custom

  • flatfile

  • reliable

Note

  • Any string other than the ones listed here will cause an error at run time.

If this property is set to "custom", the Reference property is required. Also, a custom parser component has to be registered with the server for input documents with this property set to "custom". For more information about custom parser components, see Parsers.

All document instances must have the same document type as the associated envelope. For example, if Format is set to "x12", the Type property of the IBizTalkDocument objects must also be "x12".

If Format is set to X12, edifact, or reliable, the Reference property should not be set.

For more information about envelope formats, see Create envelopes.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Envelopes


NameSpace Property

Contains a string that resolves naming conflicts between elements in an envelope specification.

Member List

IBizTalkEnvelope

|--Content

|--Format

|--NameSpace

|--Reference

|--Version

Property Declaration

[Visual Basic]

Property NameSpace As String

[C++]

HRESULT get_NameSpace(

BSTR* NameSpace

);

Parameters

NameSpace

[out, retval] In C++, contains the namespace. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the namespace.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value. The Reference property is checked when the Create or the Save method is called. If this string is not empty when Create is called, the Content property is set to the contents of the envelope specification, and NameSpace is changed to the value found in the envelope specification.

Once you have created or saved an object with Reference set to an envelope specification, any changes you make to the Content or NameSpace of the referenced envelope specification are not automatically updated on the referring object. To update the object that refers to the revised envelope specification, you must save the envelope specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

Note

  • When creating an envelope, the number of characters in the NameSpace combined with the number of characters in the specification name cannot exceed 255.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Reference Property

Contains a full Web Distributed Authoring and Versioning (WebDAV) URL name of the envelope format specification file.

Member List

IBizTalkEnvelope

|--Content

|--Format

|--NameSpace

|--Reference

|--Version

Property Declaration

[Visual Basic]

Property Reference As String

[C++]

HRESULT get_Reference(

BSTR* Reference

);

HRESULT put_Reference(

BSTR Reference

);

Parameters

Reference

[out, retval], [in] In C++, contains the reference. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the reference.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property if the Format property is set to "custom". Reference is checked when the Create or the Save method is called. If this string is not empty when Create is called, the Content property is set to the contents of the envelope specification, and the NameSpace property is changed to the value found in the envelope specification.

Once you have created or saved an object with Reference set to an envelope specification, any changes you make to the Content or NameSpace of the referenced envelope specification are not automatically updated on the referring object. To update the object that refers to the revised envelope specification, you must save the envelope specification, reset the Reference property of the object to its current value, and then call Save on the referring object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Version Property

Contains the version of the envelope format specification.

Member List

IBizTalkEnvelope

|--Content

|--Format

|--NameSpace

|--Reference

|--Version

Property Declaration

[Visual Basic]

Property Version As String

[C++]

HRESULT get_Version(

BSTR* Version

);

Parameters

Version

[out, retval] In C++, contains the version. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the version.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkLoggingInfo

Configures the document-logging information for an associated IBizTalkChannel object.

Hierarchy

IDispatch

|--IBizTalkLoggingInfo

Declaration

[Visual Basic]

Class BizTalkLoggingInfo

[C++]

interface IBizTalkLoggingInfo : IDispatch

Members

IBizTalkLoggingInfo defines the following properties:

Property | Description
LogNativeInputDocument | Contains a value that indicates whether the input document instance is saved and logged in its native format.
LogNativeOutputDocument | Contains a value that indicates whether the output document instance is saved and logged in its native format.
LogXMLInputDocument | Contains a value that indicates whether the XML input document is saved and logged.
LogXMLOutputDocument | Contains a value that indicates whether the XML output document is saved and logged.

Remarks

The IBizTalkLoggingInfo object is automatically created when an IBizTalkChannel object is instantiated with the CreateChannel method of the IBizTalkConfig object. You can access the IBizTalkLoggingInfo object by using the LoggingInfo property of the IBizTalkChannel object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


LogNativeInputDocument Property

Contains a value that indicates whether the input document instance is saved and logged in its native format.

Member List

IBizTalkLoggingInfo

|--LogNativeInputDocument

|--LogNativeOutputDocument

|--LogXMLInputDocument

|--LogXMLOutputDocument

Property Declaration

[Visual Basic]

Property LogNativeInputDocument As Boolean

[C++]

HRESULT get_LogNativeInputDocument(

VARIANT_BOOL* LogNativeInDoc

);

HRESULT put_LogNativeInputDocument(

VARIANT_BOOL LogNativeInDoc

);

Parameters

LogNativeInDoc

[out, retval], [in] In C++, contains a value that indicates whether or not the input documents will be saved and logged in their native format. VARIANT_TRUE indicates that the input documents will be saved and logged in their native formats; VARIANT_FALSE indicates that the input documents will not be saved and logged in their native formats. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the input documents will be saved and logged in their native format. True indicates that the input documents will be saved and logged in their native formats; False indicates that the input documents will not be saved and logged in their native formats.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


LogNativeOutputDocument Property

Contains a value that indicates whether the output document instance is saved and logged in its native format.

Member List

IBizTalkLoggingInfo

|--LogNativeInputDocument

|--LogNativeOutputDocument

|--LogXMLInputDocument

|--LogXMLOutputDocument

Property Declaration

[Visual Basic]

Property LogNativeOutputDocument As Boolean

[C++]

HRESULT get_LogNativeOutputDocument(

VARIANT_BOOL* LogNativeOutDoc

);

HRESULT put_LogNativeOutputDocument(

VARIANT_BOOL LogNativeOutDoc

);

Parameters

LogNativeOutDoc

[out, retval], [in] In C++, contains a value that indicates whether or not the output documents will be saved and logged in their native format. VARIANT_TRUE indicates that the output documents will be saved and logged in their native formats; VARIANT_FALSE indicates that the output documents will not be saved and logged in their native formats. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the output documents will be saved and logged in their native format. True indicates that the output documents will be saved and logged in their native formats; False indicates that the output documents will not be saved and logged in their native formats.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


LogXMLInputDocument Property

Contains a value that indicates whether the XML input document is saved and logged.

Member List

IBizTalkLoggingInfo

|--LogNativeInputDocument

|--LogNativeOutputDocument

|--LogXMLInputDocument

|--LogXMLOutputDocument

Property Declaration

[Visual Basic]

Property LogXMLInputDocument As Boolean

[C++]

HRESULT get_LogXMLInputDocument(

VARIANT_BOOL* LogXMLInDoc

);

HRESULT put_LogXMLInputDocument(

VARIANT_BOOL LogXMLInDoc

);

Parameters

LogXMLInDoc

[out, retval], [in] In C++, contains a value that indicates whether or not the input documents will be saved and logged in XML format. VARIANT_TRUE indicates that the input documents will be saved and logged in XML format; VARIANT_FALSE indicates that the input documents will not be saved and logged in XML format. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the input documents will be saved and logged in XML format. VARIANT_TRUE indicates that the input documents will be saved and logged in XML format; VARIANT_FALSE indicates that the input documents will not be saved and logged in XML format.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


LogXMLOutputDocument Property

Contains a value that indicates whether the XML output document is saved and logged.

Member List

IBizTalkLoggingInfo

|--LogNativeInputDocument

|--LogNativeOutputDocument

|--LogXMLInputDocument

|--LogXMLOutputDocument

Property Declaration

[Visual Basic]

Property LogXMLOutputDocument As Boolean

[C++]

HRESULT get_LogXMLOutputDocument(

VARIANT_BOOL* LogXMLOutDoc

);

HRESULT put_LogXMLOutputDocument(

VARIANT_BOOL LogXMLOutDoc

);

Parameters

LogXMLOutDoc

[out, retval], [in] In C++, contains a value that indicates whether or not the output documents will be saved and logged in XML format. VARIANT_TRUE indicates that the output documents will be saved and logged in XML format; VARIANT_FALSE indicates that the output documents will not be saved and logged in XML format. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the output documents will be saved and logged in XML format. VARIANT_TRUE indicates that the output documents will be saved and logged in XML format; VARIANT_FALSE indicates that the output documents will not be saved and logged in XML format.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Storage


IBizTalkOrganization

Configures an organization, its organization identifiers (aliases), and the applications within the organization that send and/or receive documents. The application indicates the ultimate source or destination of the document.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkOrganization

Declaration

[Visual Basic]

Class BizTalkOrganization

[C++]

interface IBizTalkOrganization : IBizTalkBase

Members

IBizTalkOrganization defines the following properties:

Property | Description
Aliases | Contains an ADO recordset of aliases that refer to the object.
Applications | Contains an ADO recordset of applications that refer to the object.
Comments | Contains user comments for the object.
DateModified | Contains the date and time at which the information in the object was created or last modified.
Handle | Contains the handle to the object.
IsDefault | Contains a value that indicates whether the object is the default organization.
Name | Contains the name of the object.

IBizTalkOrganization defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
CreateAlias | Creates an alias for the object.
CreateApplication | Creates a new application.
GetDefaultAlias | Retrieves the default alias for the object.
Load | Loads a specified object in memory.
LoadAlias | Loads an existing alias for the object in memory.
LoadApplication | Loads an application in memory.
LoadByName | Loads a specified object by name in memory.
Remove | Removes the object from the database.
RemoveAlias | Removes an alias.
RemoveApplication | Removes an application.
Save | Saves the object in the database.
SaveAlias | Saves the alias.
SaveApplication | Saves the application.

Remarks

An IBizTalkOrganization object can have more than one application, but each application name must be unique for that object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


Aliases Property

Contains an ADO recordset of aliases that refer to the object.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Property Declaration

[Visual Basic]

Property Aliases As Object

[C++]

HRESULT get_Aliases(

IDispatch** AliasesDisp

);

Parameters

AliasesDisp

[out, retval] Contains all aliases that refer to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all aliases that refer to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

The alias for an object is the organization qualifier/value pair. BizTalk Messaging Manager refers to aliases as identifiers.

Each record in the ADO recordset returned by this property contains information about the aliases of an existing IBizTalkOrganization object in the database. The fields in each record contain the following information, listed in order:

  • Handle assigned to the alias.

  • Name specified in the CreateAlias method.

  • Boolean specified in the CreateAlias method.

  • Qualifier specified in the CreateAlias method.

  • Value specified in the CreateAlias method.

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


Applications Property

Contains an ADO recordset of applications that refer to the object.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Property Declaration

[Visual Basic]

Property Applications As Object

[C++]

HRESULT get_Applications(

IDispatch** ApplicationsDisp

);

Parameters

ApplicationsDisp

[out, retval] Contains all applications that refer to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns all applications that refer to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about the applications of an existing IBizTalkOrganization object in the database. The fields in each record contain the following information, listed in order:

  • Handle assigned to the application.

  • Name specified in the CreateApplication method.

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Comments Property

Contains user comments for the object.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Property Declaration

[Visual Basic]

Property Comments As String

[C++]

HRESULT get_Comments(

BSTR* Comments

);

HRESULT put_Comments(

BSTR Comments

);

Parameters

Comments

[out, retval], [in] In C++, contains the comments. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the comments.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string ("").

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


CreateAlias Method

Creates an alias for the object.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub CreateAlias( _

Name As String, _

Default As Boolean, _

Qualifier As String, _

Value As String _

)

[C++]

HRESULT CreateAlias(

BSTR Name,

VARIANT_BOOL Default,

BSTR Qualifier,

BSTR Value

);

Parameters

Name

[in] Contains the name of the alias.

Default

[in] In Visual Basic, contains a value that indicates whether or not this default alias overrides the previous default alias. True indicates that this default alias overrides the previous default alias; False indicates that this default alias should not override the previous default alias. If no alias is specified as the default, one is assigned when the Create method is called.

[in] In C++, contains a value that indicates whether or not this default alias overrides the previous default alias. VARIANT_TRUE indicates that this default alias overrides the previous default alias; VARIANT_FALSE indicates that this default alias should not override the previous default alias. If no alias is specified as the default, one is assigned when the Create method is called.

Qualifier

[in] Contains the qualifier. This parameter cannot be set to "group".

Value

[in] Contains the value.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The alias for an object is the organization identifier that contains a name and a qualifier/value pair.

More than one alias can be created for an IBizTalkOrganization object. The organization alias must contain a name that is unique for the specified IBizTalkOrganization object, and a qualifier/value pair that is unique across all IBizTalkOrganization objects. One of these aliases must be specified as the default alias for the object.

The server automatically creates an alias named Organization with a default identifier of OrganizationName and the value set to the organization's name for new organizations. If the organization name is changed, the value is automatically updated with the new name. This alias cannot be removed.

Note

  • When using envelopes with an EDIFACT format and you want to use a null value for the empty qualifier in the header for the source or the destination, create a custom identifier with a single dash (-) as the qualifier.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


CreateApplication Method

Creates a new application.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub CreateApplication( _

Name As String _

)

[C++]

HRESULT CreateApplication(

BSTR Name

);

Parameters

Name

[in] Contains the name of the application.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

If an IBizTalkOrganization object is associated with more than one application, each application name must be unique.

Notes

  • BizTalk Messaging Manager refers to the default organization as the home organization.

  • BizTalk Messaging Manager allows applications to be created for the home organization only. The BizTalk Messaging Configuration object model does not enforce this restriction. Therefore, if you create an application for an organization other than the default (home) organization, you cannot modify it using BizTalk Messaging Manager.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


GetDefaultAlias Method

Retrieves the default alias for the object.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Function GetDefaultAlias( ) As Long

[C++]

HRESULT GetDefaultAlias(

long* AliasHandle

);

Parameters

AliasHandle

[out, retval] Contains the handle. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the handle.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The default alias for an object is the default organization identifier type/value pair.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


IsDefault Property

Contains a value that indicates whether the object is the default organization.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Property Declaration

[Visual Basic]

Property IsDefault( ) As Boolean

[C++]

HRESULT get_IsDefault(

VARIANT_BOOL* IsDefault

);

Parameters

IsDefault

In C++, contains a value that indicates whether or not this organization is the default organization. VARIANT_TRUE indicates that this organization is the default organization; VARIANT_FALSE indicates that this organization is not the default organization. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not this organization is the default organization. True indicates that this organization is the default organization; False indicates that this organization is not the default organization.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property. There must be one and only one default organization at any time.

Note

  • BizTalk Messaging Manager refers to the default organization as the home organization.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


LoadAlias Method

Loads an existing alias for the object in memory.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub LoadAlias( _

AliasHandle As Long, _

Name As Variant, _

Default As Variant, _

Qualifier As Variant, _

Value As Variant _

)

[C++]

HRESULT LoadAlias(

long AliasHandle,

VARIANT* Name,

VARIANT* Default,

VARIANT* Qualifier,

VARIANT* Value

);

Parameters

AliasHandle

[in] Contains the handle to the alias.

Name

[in, out] Contains the name of the organization identifier.

Default

[in, out] Contains the default flag.

Qualifier

[in, out] Contains the qualifier of the organization identifier.

Value

[in, out] Contains the value of the organization identifier.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The alias for an object is the organization qualifier/value pair.

The values used with the parameters of this method can be obtained from the Aliases property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


LoadApplication Method

Loads an application in memory.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub LoadApplication( _

ApplicationHandle As Long, _

Name As Variant _

)

[C++]

HRESULT LoadApplication(

long ApplicationHandle,

VARIANT* Name

);

Parameters

ApplicationHandle

[in] Contains the application handle.

Name

[in, out] Contains the name of the application.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The values used with the parameters of this method can be obtained from the Applications property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


RemoveAlias Method

Removes an alias.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub RemoveAlias( _

AliasHandle As Long _

)

[C++]

HRESULT RemoveAlias(

long AliasHandle

);

Parameters

AliasHandle

[in] Contains the handle to the alias.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This record cannot be removed if any of the following conditions apply:

  • An IBizTalkPort or an IBizTalkChannel object refers to it.

  • It has been designated the default organization identifier.

  • This alias was autogenerated.

The alias handle can be obtained from the Aliases property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


RemoveApplication Method

Removes an application.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub RemoveApplication( _

ApplicationHandle As Long _

)

[C++]

HRESULT RemoveApplication(

long ApplicationHandle

);

Parameters

ApplicationHandle

[in] Contains the handle.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This record cannot be removed if an IBizTalkPort or an IBizTalkChannel object refers to it.

The application handle can be obtained from the Applications property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SaveAlias Method

Saves the alias.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub SaveAlias( _

AliasHandle As Long, _

Name As String, _

Default As Boolean, _

Qualifier As String, _

Value As String _

)

[C++]

HRESULT SaveAlias(

long AliasHandle,

BSTR Name,

VARIANT_BOOL Default,

BSTR Qualifier,

BSTR Value

);

Parameters

AliasHandle

[in] Contains the handle to the alias.

Name

[in] Contains the name of the organization identifier. This parameter cannot be changed if this alias was autogenerated.

Default

[in] In Visual Basic, contains a value that indicates whether or not this is the default alias for the organization. True indicates that this is the default alias for the organization; False indicates that this is not the default alias for the organization.

[in] In C++, contains a value that indicates whether or not this is the default alias for the organization. VARIANT_TRUE indicates that this is the default alias for the organization; VARIANT_FALSE indicates that this is not the default alias for the organization.

Qualifier

[in] Contains the qualifier of the organization identifier. This parameter cannot be changed if this alias was autogenerated. This parameter cannot be set to "group".

Value

[in] Contains the value of the organization identifier. This parameter cannot be changed if this alias was autogenerated.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The alias for an object is the organization identifier type/value pair.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Organizations


SaveApplication Method

Saves the application.

Member List

IBizTalkOrganization

|--Aliases

|--Applications

|--Comments

|--CreateAlias

|--CreateApplication

|--GetDefaultAlias

|--IsDefault

|--LoadAlias

|--LoadApplication

|--RemoveAlias

|--RemoveApplication

|--SaveAlias

|--SaveApplication

Method Declaration

[Visual Basic]

Sub SaveApplication( _

ApplicationHandle As Long, _

Name As String _

)

[C++]

HRESULT SaveApplication(

long ApplicationHandle,

BSTR Name

);

Parameters

ApplicationHandle

[in] Contains the handle to the application.

Name

[in] Contains the name of the application.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkPort

Configures a one-way transfer of a document between organizations and applications. It identifies the source organization and/or application, the destination organization and/or application, the primary transport type, and, if selected, the associated envelope for transmission.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkPort

Declaration

[Visual Basic]

Class BizTalkPort

[C++]

interface IBizTalkPort : IBizTalkBase

Members

IBizTalkPort defines the following properties:

Property | Description
Channels | Contains an ADO recordset that includes information about all IBizTalkChannel objects that refer to the object.
Comments | Contains the user comments for the IBizTalkPort object.
ControlNumberValue | Contains the value of the interchange control number.
DateModified | Contains the date and time at which the information in the object was created or last modified.
Delimiters | Contains an IDictionary object that includes all delimiters used in the document specification.
DestinationEndpoint | Contains information about the destination.
EncodingType | Contains an enumeration value that indicates the type of document encoding.
EncryptionCertificateInfo | Contains information about the certificate that encrypts the document.
EncryptionType | Contains an enumeration value that indicates the type of document encryption.
Envelope | Contains a handle to the IBizTalkEnvelope object associated with this IBizTalkPort object.
Handle | Contains the handle to the object.
Name | Contains the name of the object.
PrimaryTransport | Contains the primary transport component information.
SecondaryTransport | Contains the secondary transport component information.
ServiceWindowInfo | Contains the service window information.
SignatureType | Contains an enumeration value that indicates the type of digital signing and verification.

IBizTalkPort defines the following methods:

Method | Description
Clear | Clears the object from memory.
Create | Creates a new object in the database.
Load | Loads a specified object in memory.
LoadByName | Loads a specified object by name in memory.
Remove | Removes the object from the database.
Save | Saves the object in the database.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Document Processing

Messaging Ports


Channels Property

Contains an ADO recordset that includes information about all IBizTalkChannel objects that refer to the object.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property Channels( ) As Object

[C++]

HRESULT get_Channels(

IDispatch** ChannelsDisp

);

Parameters

ChannelsDisp

[out, retval] Contains the IBizTalkChannel objects that refer to the object.

Return Values

In Visual Basic, this property returns the IBizTalkChannel objects that refer to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property with no default value.

Each record in the ADO recordset returned by this property contains information about the IBizTalkChannel objects in the database that are associated with this IBizTalkPort object. The fields in each record contain the following information, listed in order:

  • Handle

  • Name

  • A unique channel identifier, in GUID format.

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Comments Property

Contains the user comments for the IBizTalkPort object.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property Comments As String

[C++]

HRESULT get_Comments(

BSTR* Comments

);

HRESULT put_Comments(

BSTR Comments

);

Parameters

Comments

[out, retval], [in] In C++, contains the comments. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the comments.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of an empty string ("").

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


ControlNumberValue Property

Contains the value of the interchange control number.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property ControlNumberValue As String

[C++]

HRESULT get_ControlNumberValue(

BSTR* ControlNumberValue

);

HRESULT put_ControlNumberValue(

BSTR ControlNumberValue

);

Parameters

ControlNumberValue

[out, retval], [in] In C++, contains the interchange control number. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property the interchange control number.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The ControlNumberValue property must contain a value between 1 and 999999999. This property has no default value.

This is a required property if the Format property of the associated IBizTalkEnvelope object is set to "x12", "edifact", or "custom". This constraint is not enforced for this release, but the server fails if it is not adhered to.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Delimiters Property

Contains an IDictionary object that includes all delimiters used in the document specification.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property Delimiters As Object

[C++]

HRESULT get_Delimiters(

IDispatch** DelimitersDisp

);

HRESULT putref_Delimiters(

IDispatch* DelimitersDisp

);

Parameters

DelimitersDisp

[out, retval], [in] In C++, contains the delimiters. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the delimiters.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property for the object to be complete if the Format property of the associated IBizTalkEnvelope object is set to "x12", "edifact", or "custom". Delimiters specifies which characters to use to separate data within the envelope and the documents that are sent using this envelope.

The PropertySet property of the associated IBizTalkDocument object must also be defined. The following table shows which names are required for the delimiters of the IDictionary object for various formats:

Delimiter | X12 | EDIFACT
Record_delim | Yes | Yes
Field_delim | Yes | Yes
Subfield_delim | Yes | Yes
Escape_char | No | Yes

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


DestinationEndpoint Property

Contains information about the destination.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property DestinationEndpoint As Object

[C++]

HRESULT get_DestinationEndpoint(

IDispatch** DestEndpointDisp

);

HRESULT putref_DestinationEndpoint(

IDispatch* DestEndpointDisp

);

Parameters

DestEndpointDisp

[out, retval], [in] In C++, contains information about the destination. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns information about the destination.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information provided by this property includes the Alias, Application, and Organization properties and is created and stored in memory in the IBizTalkEndPoint object.

Once an IBizTalkPort object has been created, the destination IBizTalkOrganization object cannot be changed.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


EncodingType Property

Contains an enumeration value that indicates the type of document encoding.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property EncodingType As BIZTALK_ENCODING_TYPE

[C++]

HRESULT get_EncodingType(

BIZTALK_ENCODING_TYPE* EncodingType

);

HRESULT put_EncodingType(

BIZTALK_ENCODING_TYPE EncodingType

);

Parameters

EncodingType

[out, retval], [in] In C++, contains the encoding type. Valid values for this parameter are defined by the BIZTALK_ENCODING_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_ENCODING_TYPE enumeration, indicating the encoding type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of BIZTALK_ENCODING_TYPE_NONE. The Clear method sets EncodingType to BIZTALK_ENCODING_TYPE_NONE.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


EncryptionCertificateInfo Property

Contains information about the certificate that encrypts the document.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property EncryptionCertificateInfo As Object

[C++]

HRESULT get_EncryptionCertificateInfo(

IDispatch** EncryptionCertificateInfoDisp

);

HRESULT putref_EncryptionCertificateInfo(

IDispatch* EncryptionCertificateInfoDisp

);

Parameters

EncryptionCertificateInfoDisp

[out, retval], [in] In C++, contains the certificate information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the certificate information.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information provided by this property includes the Name, Reference, Store, and Usage properties and is created and stored in memory in the IBizTalkCertificateInfo object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


EncryptionType Property

Contains an enumeration value that indicates the type of document encryption.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property EncryptionType As BIZTALK_ENCRYPTION_TYPE

[C++]

HRESULT get_EncryptionType(

BIZTALK_ENCRYPTION_TYPE* EncryptionType

);

HRESULT put_EncryptionType(

BIZTALK_ENCRYPTION_TYPE EncryptionType

);

Parameters

EncryptionType

[out, retval], [in] In C++, contains the encryption type. Valid values for this parameter are defined by the BIZTALK_ENCRYPTION_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_ENCRYPTION_TYPE enumeration, indicating the encoding type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of BIZTALK_ENCRYPTION_TYPE_NONE. The Clear method sets EncryptionType to BIZTALK_ENCRYPTION_TYPE_NONE.

If the EncryptionType is set to BIZTALK_ENCRYPTION_TYPE_SMIME, then the EncryptionCertificateInfo property must be set.

For open messaging ports, EncryptionType must be set to BIZTALK_ENCRYPTION_TYPE_NONE.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Envelope Property

Contains a handle to the IBizTalkEnvelope object associated with this IBizTalkPort object.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property Envelope As Long

[C++]

HRESULT get_Envelope(

long* EnvelopeHandle

);

HRESULT put_Envelope(

long EnvelopeHandle

);

Parameters

EnvelopeHandle

[out, retval], [in] In C++, contains the handle to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the handle to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Envelopes


PrimaryTransport Property

Contains the primary transport component information.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property PrimaryTransport As Object

[C++]

HRESULT get_PrimaryTransport(

IDispatch** TransportInfoDisp

);

HRESULT putref_PrimaryTransport(

IDispatch* TransportInfoDisp

);

Parameters

TransportInfoDisp

[out, retval], [in] In C++, contains the primary transport component information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the primary transport component information.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property for the object.

Information provided by this property includes the Address, Parameter, and Type properties of the IBizTalkTransportInfo object.

The following constraints are enforced:

  • If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_EX_DESTINATION, the Address property cannot be set, and PrimaryTransport must be set to BIZTALK_TRANSPORT_TYPE_OPENDESTINATION. The IBizTalkServiceWindowInfo object cannot be used with open destination ports.

  • Once an IBizTalkPort object has been created, the Openness property of the associated IBizTalkEndPoint object cannot be changed.

  • The Openness property cannot be set to BIZTALK_OPENNESS_TYPE_EX_SOURCE or BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW.

  • When using a Type of BIZTALK_TRANSPORT_TYPE_LOOPBACK, the primary and secondary transport Address property cannot be set, and the IBizTalkServiceWindowInfo object cannot be used.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SecondaryTransport Property

Contains the secondary transport component information.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property SecondaryTransport As Object

[C++]

HRESULT get_SecondaryTransport(

IDispatch** TransportInfoDisp

);

HRESULT putref_SecondaryTransport(

IDispatch* TransportInfoDisp

);

Parameters

TransportInfoDisp

[out, retval], [in] In C++, contains the secondary transport component information. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the secondary transport component information.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. This is a required property for the object to be complete.

Information provided by this property includes the Address, Parameter, and Type properties, and is created and stored in memory in the IBizTalkTransportInfo object.

The following constraints are enforced:

  • If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_EX_DESTINATION, the Address property cannot be set, and SecondaryTransport must be set to BIZTALK_TRANSPORT_TYPE_OPENDESTINATION.

  • Once an IBizTalkPort object has been created, the Openness property of the associated IBizTalkEndPoint object cannot be changed.

  • The Openness property cannot be set to BIZTALK_OPENNESS_TYPE_EX_SOURCE or BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW.

  • The Type property cannot be set to BIZTALK_TRANSPORT_TYPE_LOOPBACK.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


ServiceWindowInfo Property

Contains the service window information.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property ServiceWindowInfo As Object

[C++]

HRESULT get_ServiceWindowInfo(

IDispatch** ServiceWindowInfoDisp

);

HRESULT putref_ServiceWindowInfo(

IDispatch* ServiceWindowInfoDisp

);

Parameters

ServiceWindowInfoDisp

[out, retval], [in] In C++, contains the service window. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the service window.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Information provided by this property includes the FromTime, IsEnabled, and ToTime properties and is created and stored in memory in the IBizTalkServiceWindowInfo object.

If this property is used, the IBizTalkServiceWindowInfo object must specify a valid time range by using the FromTime and ToTime properties.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


SignatureType Property

Contains an enumeration value that indicates the type of digital signing and verification.

Member List

IBizTalkPort

|--Channels

|--Comments

|--ControlNumberValue

|--Delimiters

|--DestinationEndpoint

|--EncodingType

|--EncryptionCertificateInfo

|--EncryptionType

|--Envelope

|--PrimaryTransport

|--SecondaryTransport

|--ServiceWindowInfo

|--SignatureType

Property Declaration

[Visual Basic]

Property SignatureType As BIZTALK_SIGNATURE_TYPE

[C++]

HRESULT get_SignatureType(

BIZTALK_SIGNATURE_TYPE* SignatureType

);

HRESULT put_SignatureType(

BIZTALK_SIGNATURE_TYPE SignatureType

);

Parameters

SignatureType

[out, retval], [in] In C++, contains the signature type. Valid values for this parameter are defined by the BIZTALK_SIGNATURE_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_SIGNATURE_TYPE enumeration, indicating the encoding type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has a default value of BIZTALK_SIGNATURE_TYPE_NONE. The Clear method sets SignatureType to BIZTALK_SIGNATURE_TYPE_NONE.

IBizTalkPort objects associated with open channels cannot have a SignatureType.

If the SignatureType on an IBizTalkPort object is changed from BIZTALK_SIGNATURE_TYPE_NONE to BIZTALK_SIGNATURE_TYPE_SMIME, all channels associated with this IBizTalkPort object must have already been saved with SignatureCertificateInfo. Also, if a IBizTalkChannel contains a SignatureCertificateInfo object and the SignatureType of the IBizTalkPort is set to BIZTALK_SIGNATURE_TYPE_NONE, the signature will be ignored.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkPortGroup

Configures port groups that are used to distribute the same document to many organizations.

Hierarchy

IDispatch

|--IBizTalkBase

|--IBizTalkPortGroup

Declaration

[Visual Basic]

Class BizTalkPortGroup

[C++]

interface IBizTalkPortGroup : IBizTalkBase

Members

IBizTalkPortGroup defines the following properties:

Property | Description
Channels | Contains an ADO recordset that contains information about all IBizTalkChannel objects that refer to this object.
DateModified | Contains the date and time at which the information in the object was created or last modified.
Handle | Contains the handle to the object.
Name | Contains the name of the object.
Ports | Contains an ADO recordset that contains information about all IBizTalkPort objects that refer to this object.

IBizTalkPortGroup defines the following methods:

Method | Description
AddPort | Adds an IBizTalkPort object to this port group. There must be at least one IBizTalkPort object in the port group.
Clear | Clears the object from memory.
Create | Creates a new object in the database.
Load | Loads a specified object in memory.
LoadByName | Loads a specified object by name in memory.
Remove | Removes the object from the database.
RemovePort | Removes an IBizTalkPort object from the port group. There must be at least one IBizTalkPort object in the port group.
Save | Saves the object in the database.

Remarks

There must always be at least one IBizTalkPort object and one IBizTalkChannel object associated with a IBizTalkPortGroupobject. The IBizTalkChannel object is associated with the IBizTalkPortGroup object, not the IBizTalkPort object within the group. Each IBizTalkPort object within the group has another IBizTalkChannel object or objects associated with it, but these are ignored when the port group channel is invoked.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Distribution List

Port Groups

Submitting Documents to a Port Group


AddPort Method

Adds an IBizTalkPort object to this port group. There must be at least one IBizTalkPort object in the port group.

Member List

IBizTalkPortGroup

|--AddPort

|--Channels

|--Ports

|--RemovePort

Method Declaration

[Visual Basic]

Sub AddPort( _

PortHandle As Long _

)

[C++]

HRESULT AddPort(

long PortHandle

);

Parameters

PortHandle

[in] Contains the handle to the object.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The following constraints apply to this method:

  • There must be at least one IBizTalkPort in this IBizTalkPortGroup object.

  • The Openness property of the associated BizTalkEndPoint object to be added must be set to BIZTALK_OPENNESS_TYPE_NOTOPEN.

  • The port group specified by this object cannot contain any duplicate IBizTalkPort objects.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Channels Property

Contains an ADO recordset that contains information about all IBizTalkChannel objects that refer to this object.

Member List

IBizTalkPortGroup

|--AddPort

|--Channels

|--Ports

|--RemovePort

Property Declaration

[Visual Basic]

Property Channels As Object

[C++]

HRESULT get_Channels(

IDispatch** ChannelsDisp

);

Parameters

ChannelsDisp

[out, retval] Contains an ADO recordset that contains all IBizTalkChannel objects that refer to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns an ADO recordset that contains all IBizTalkChannel objects that refer to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Each record in the ADO recordset returned by this property contains information about the IBizTalkChannel objects in the database that are associated with this IBizTalkPortGroup object. The fields in each record contain the following information, listed in order:

  • Handle

  • Name

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Ports Property

Contains an ADO recordset that contains information about all IBizTalkPort objects that refer to this object.

Member List

IBizTalkPortGroup

|--AddPort

|--Channels

|--Ports

|--RemovePort

Property Declaration

[Visual Basic]

Property Ports As Object

[C++]

HRESULT Ports(

IDispatch** PortsDisp

);

Parameters

PortsDisp

[out, retval] Contains an ADO recordset that includes all IBizTalkPort objects that refer to the object. This parameter is not supported in Visual Basic. For more information, see "Return Values.

Return Values

In Visual Basic, this property returns an ADO recordset that includes all IBizTalkPort objects that refer to the object.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. Each record in the ADO recordset returned by this property contains information about the IBizTalkPort objects in the database that are associated with this IBizTalkPortGroup object. The fields in each record contain the following information, listed in order:

  • Handle

  • Name

Additional information about Microsoft ActiveX Data Objects is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


RemovePort Method

Removes an IBizTalkPort object from the port group. There must be at least one IBizTalkPort object in the port group.

Member List

IBizTalkPortGroup

|--AddPort

|--Channels

|--Ports

|--RemovePort

Method Declaration

[Visual Basic]

Sub RemovePort( _

PortHandle As Long _

)

[C++]

HRESULT RemovePort(

long PortHandle

);

Parameters

PortHandle

[in] Contains the handle to the object to remove.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Note

  • In addition to the HRESULT values listed on the error messages page, this method returns OLEDB provider errors. Additional information about OLEDB is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The last IBizTalkPort object associated with the object cannot be removed. An IBizTalkPort object cannot be removed if an IBizTalkChannel object refers to it.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkServiceWindowInfo

Configures the service window for an associated IBizTalkPort object. The service window indicates a valid time range for transmitting documents.

Hierarchy

IDispatch

|--IBizTalkServiceWindowInfo

Declaration

[Visual Basic]

Class BizTalkServiceWindowInfo

[C++]

interface IBizTalkServiceWindowInfo : IDispatch

Members

IBizTalkServiceWindowInfo defines the following properties:

Property | Description
FromTime | Contains the earliest time that the interchange can be transmitted.
IsEnabled | Contains a value that indicates whether the service window is enabled.
ToTime | Contains the latest time that the interchange can be transmitted.

Remarks

The IBizTalkServiceWindowInfo object is automatically created when an IBizTalkPort object is instantiated with the CreatePort method of the IBizTalkConfig object. Access the properties of the IBizTalkServiceWindowInfo object by using the ServiceWindowInfo property of the IBizTalkPort object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


FromTime Property

Contains the earliest time that the interchange can be transmitted.

Member List

IBizTalkServiceWindowInfo

|--FromTime

|--IsEnabled

|--ToTime

Property Declaration

[Visual Basic]

Property FromTime As String

[C++]

HRESULT get_FromTime(

BSTR* FromTime

);

HRESULT put_Comments(

BSTR FromTime

);

Parameters

FromTime

[out, retval], [in] In C++, contains the earliest time that the interchange can be transmitted. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the earliest time that the interchange can be transmitted.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The FromTime property must contain an integer value between 0 and 23. Fractional values and minutes cannot be specified. Service window hours are displayed in the coordinated universal time (UTC) format and reflect the time on the database server.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IsEnabled Property

Contains a value that indicates whether the service window is enabled.

Member List

IBizTalkServiceWindowInfo

|--FromTime

|--IsEnabled

|--ToTime

Property Declaration

[Visual Basic]

Property IsEnabled As Boolean

[C++]

HRESULT get_IsEnabled(

VARIANT_BOOL* IsEnabled

);

HRESULT put_IsEnabled(

_BOOL IsEnabled

);

Parameters

IsEnabled

[out, retval], [in] In C++, contains a value that indicates whether or not a service window is enabled. VARIANT_TRUE indicates that the service window is enabled; VARIANT_FALSE indicates that the service window is not enabled. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not a service window is enabled. True indicates that the service window is enabled; False indicates that the service window is not enabled.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

In C++, this property has a default value of VARIANT_FALSE. In Visual Basic, this property has a default value of False.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


ToTime Property

Contains the latest time that the interchange can be transmitted.

Member List

IBizTalkServiceWindowInfo

|--FromTime

|--IsEnabled

|--ToTime

Property Declaration

[Visual Basic]

Property ToTime As String

[C++]

HRESULT get_ToTime(

BSTR* ToTime

);

HRESULT put_ToTime(

BSTR ToTime

);

Parameters

ToTime

[out, retval], [in] In C++, contains the latest time that the interchange can be transmitted. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the latest time that the interchange can be transmitted.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The ToTime property must contain an integer value between 0 and 23. Fractional values and minutes cannot be specified. Service window hours are displayed in the coordinated universal time (UTC) format and reflect the time on the database server.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IBizTalkTransportInfo

Configures the transport service for an associated IBizTalkPort object.

Hierarchy

IDispatch

|--IBizTalkTransportInfo

Declaration

[Visual Basic]

Class BizTalkTransportInfo

[C++]

interface IBizTalkTransportInfo : IDispatch

Members

IBizTalkTransportInfo defines the following properties:

Property | Description
Address | Contains the destination address of the primary transport component.
Parameter | Contains the required return e-mail address for the associated source IBizTalkOrganization object if the Type property is BIZTALK_TRANSPORT_ TYPE_SMTP.
Type | Contains an enumeration value that indicates the type of transport component to be used for the primary transport.

Remarks

The IBizTalkTransportInfo object is automatically created when an IBizTalkPort object is instantiated with the CreatePort method of the IBizTalkConfig object.

Access the IBizTalkTransportInfo object by using the PrimaryTransport or SecondaryTransport property of the IBizTalkPort object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Address Property

Contains the destination address of the primary transport component.

Member List

IBizTalkTransportInfo

|--Address

|--Parameter

|--Type

Property Declaration

[Visual Basic]

Property Address As String

[C++]

HRESULT get_Address(

BSTR* TransportAddress

);

HRESULT put_Address(

BSTR TransportAddress

);

Parameters

TransportAddress

[out, retval], [in] In C++, contains the address. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the address.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_DESTINATION, Address cannot be set, and the Type property must be set to BIZTALK_TRANSPORT_TYPE_OPENDESTINATION.

Address must have one of the following prefixes, according to the Type property:

Transport type | Prefix | Example Address value
APPINTEGRATION | Not applicable | {11111111-1111-1111-1111-111111111111}
FILE | file:// | file://C:\Test\MyFile.xml
HTTP | http:// | http://www.adatum.com/repository/bts.asp
HTTPS | https:// | https://www.adatum.com/secure/btss.asp
LOOPBACK | Not applicable | Not applicable
MSMQ | Not applicable | DIRECT=OS:.\private$\myqueue
NONE | Not applicable | Not applicable
OPENDESTINATION | Not applicable | Not applicable
ORCHESTRATIONACTIVATION | Not applicable | C:\XLANG\Schedules\mysched.skx
SMTP | mailto: | mailto:patricia@adatum.com

Notes

  • The queue:// prefix must be used with an open messaging port when a Message Queue is specified as the destination address. For open messaging ports, the address is specified either in the document instance or as a parameter when submitting the document. For more information, see Routing.

  • When using the Orchestration Activation Component transport type, the Address property must contain the full path of the XLANG schedule on the local computer. The file:// prefix cannot be used when specifying the path of the XLANG schedule (.skx) file.

  • When using the HTTP or HTTPS transport types, BizTalk Server sends the data using a proxy server by default. This is the correct setting to transport data to computers outside of your company's firewall. However, when sending data within your company's intranet, you can bypass the use of a proxy server. To do this, you must set the UseProxy field to False in the transport dictionary. For more information, see SetConfigData.

When using the file:// transport type, you can include symbols to modify the file name. The file name created by the server contains any static characters you specified in the Address property, along with the actual value of the symbol. For example, if the Address property is set to "file://C:\Orders\Invoice_%tracking_id%.xml", the actual file name would use a format similar to: C:\Orders\Invoice_{12345678-90AB-CDEF-1234-567890ABCDEF}. The following table contains the symbols that can be used with the file:// transport type:

Symbol | Description | Unique file name
%datetime% | Date and time, in milliseconds, of the file creation. The time is based on Greenwich Mean Time (GMT) rather than local time. | No
%src_filename% | Name of the source document processed by BizTalk Server. | No
%src_filepath% | This value is not supported. | Not applicable
%document_name% | Name of the document definition used to process the source file. | No
%server% | Host name of the server that processed the document. | No
%tracking_id% | Globally unique tracking number. | Yes
%uid% | Counter that increases over time, represented in milliseconds. This number is reset when the server is rebooted. | No

When sending reliable messaging receipts that use the SMTP transport protocol, the value specified in the identifier named Reliable Messaging Acknowledgement SMTP From Address is used as the From address. This identifier is automatically created for the default IBizTalkOrganization object. This identifier cannot be removed. You should not modify the name or qualifier for this identifier, but you can modify the value. For more information, see Processing Receipts Using Reliable Messaging.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Parameter Property

Contains the required return e-mail address of the associated source IBizTalkOrganization object if the Type property is set to BIZTALK_TRANSPORT_TYPE_SMTP.

Member List

IBizTalkTransportInfo

|--Address

|--Parameter

|--Type

Property Declaration

[Visual Basic]

Property Parameter As String

[C++]

HRESULT get_Parameter(

BSTR* PrimaryTransportParameter

);

HRESULT put_Parameter(

BSTR PrimaryTransportParameter

);

Parameters

PrimaryTransportParameter

[out, retval], [in] In C++, contains the required return e-mail address. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the required return e-mail address.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

  • This property has a default value of an empty string ("").

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


Type Property

Contains an enumeration value that indicates the type of transport component to be used for the primary transport.

Member List

IBizTalkTransportInfo

|--Address

|--Parameter

|--Type

Property Declaration

[Visual Basic]

Property Type As BIZTALK_TRANSPORT_TYPE

[C++]

HRESULT get_Type(

BIZTALK_TRANSPORT_TYPE* TransportType

);

HRESULT put_Type(

BIZTALK_TRANSPORT_TYPE TransportType

);

Parameters

TransportType

[out, retval], [in] In C++, contains the transport type. Valid values for this parameter are defined by the BIZTALK_TRANSPORT_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_TRANSPORT_TYPE enumeration, indicating the transport type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The following constraints are enforced:

  • If the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_DESTINATION, the Address property cannot be set, and Type must be set to BIZTALK_TRANSPORT_TYPE_OPENDESTINATION.

When using the Message Queuing transport type (BIZTALK_TRANSPORT_TYPE_MSMQ), the following restrictions apply:

  • When using an envelope, the maximum size of a document submitted to BizTalk Server is 4MB.

  • When an envelope is not used, the maximum size of a document submitted to BizTalk Server is 2MB.

  • When using the BIZTALK_TRANSPORT_TYPE_SMTP, the Parameter property must be set to the reply-to SMTP address.

  • The transport Type of BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION is supported only when the Openness property of the associated IBizTalkEndPoint object is set to BIZTALK_OPENNESS_TYPE_TOWORKFLOW.

  • When using the Orchestration activation component type (BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION), the maximum size of a document sent to the port on the XLANG schedule is 2MB.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)


IDictionary

Supports the creation, storage, and retrieval of name/value pairs in memory. This collection object is used by several methods in the BizTalk Messaging Configuration object model.

Hierarchy

IDispatch

|--IDictionary

Declaration

[Visual Basic]

Class CDictionary

[C++]

interface IDictionary : IDispatch

Members

IDictionary defines the following properties:

Property | Description
Count | Contains the number of entries in the IDictionary object.
Prefix | Contains the prefix that is used to exclude all entries with that prefix when the contents of the IDictionary object are saved.
Value | Contains the value associated with an entry name.

IDictionary defines the following methods:

Method | Description
GetMultiple | Returns the values of multiple entries from the IDictionary object.
PutMultiple | Adds specified entries to the IDictionary object or changes them.

Remarks

An IDictionary object is designed to be a general-purpose collection. Therefore, it can be used for anything that is supported by its internal structure. Every value in an IDictionary object is a Variant. This means that an IDictionary object can be created that consists of almost any kind of value (including other IDictionary objects).

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Count Property

Contains the number of entries in the IDictionary object.

Member List

IDictionary

|--Count

|--GetMultiple

|--Prefix

|--PutMultiple

|--Value

Property Declaration

[Visual Basic]

Property Count As Long

[C++]

HRESULT get_Count(

long* Count

);

Parameters

Count

[out, retval] In C++, contains the count. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the count.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property is read-only with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


GetMultiple Method

Returns the values of multiple entries from the IDictionary object.

Member List

IDictionary

|--Count

|--GetMultiple

|--Prefix

|--PutMultiple

|--Value

Method Declaration

[Visual Basic]

Sub GetMultiple( _

NumberOfEntries As Long, _

Entries As String, _

Values As Variant _

)

[C++]

HRESULT GetMultiple(

long NumberOfEntries,

const LPOLESTR Entries[],

VARIANT Values[]

);

Parameters

NumberOfEntries

[in] Specifies the number of values to retrieve.

Entries

[in, size_is(cb)] Array of string values that identifies the Dictionary object entries for which the values should be retrieved.

Values

[out, size_is(cb)] Array of VARIANTs. When GetMultiple returns, this array contains the values associated with the Dictionary object entries identified by the Entries[] array.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

If you call PutMultiple or GetMultiple from Microsoft Visual Basic Scripting Edition (VBScript), these methods fail because they require data types that VBScript does not support.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Prefix Property

Contains the prefix that is used to exclude all entries with that prefix when the contents of the IDictionary object are saved.

Member List

IDictionary

|--Count

|--GetMultiple

|--Prefix

|--PutMultiple

|--Value

Property Declaration

[Visual Basic]

Property Prefix As String

[C++]

HRESULT get_Prefix(

BSTR* Prefix

);

HRESULT put_Prefix(

BSTR Prefix

);

Parameters

Prefix

[out, retval], [in] In C++, contains the prefix. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the prefix.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Any name/value pair with a name beginning with the specified prefix is not saved to the database. The prefix default is an underscore (_). Therefore, any keywords that begin with an underscore are not saved unless the prefix is changed.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


PutMultiple Method

Adds specified entries to the IDictionary object or changes them.

Member List

IDictionary

|--Count

|--GetMultiple

|--Prefix

|--PutMultiple

|--Value

Method Declaration

[Visual Basic]

Sub PutMultiple( _

NumberOfEntries As Long, _

Entries As String, _

Values As Variant _

)

[C++]

HRESULT PutMultiple(

long NumberOfEntries,

const LPOLESTR Entries[],

const VARIANT Values[]

);

Parameters

NumberOfEntries

[in] Identifies the number of elements in the rgolestr and rgvar arrays.

Entries

[in, size_is(cb)] Array of strings that contains the names to add to the IDictionary object.

Values

[in, size_is(cb)] Array of VARIANTs that contains the values to add to the IDictionary object.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

A one-to-one mapping exists between the elements of the Entries[] and Values[] arrays. This means that Entries[n] is added to the IDictionary object and is initialized to Values[n]. If the element specified by Entries[n] is already in the IDictionary object, the value associated with the element is overwritten with the value stored in Values[n].

If you call PutMultiple or GetMultiple from Microsoft Visual Basic Scripting Edition (VBScript), these methods fail because they require data types that VBScript does not support.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Value Property

Contains the value associated with an entry name.

Member List

IDictionary

|--Count

|--GetMultiple

|--Prefix

|--PutMultiple

|--Value

Property Declaration

[Visual Basic]

Property Value( _

Name As String _

)

[C++]

HRESULT get_Value(

BSTR Name,

VARIANT* Value

);

HRESULT put_Value(

BSTR Name,

VARIANT Value

);

Parameters

Name

[in] Contains the name.

Value

[out, retval] [in] In C++, contains the value. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property optionally returns the value.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The value of an IDictionary object can be read or written to without explicitly using the Value property by treating the named entry as a property of the IDictionary object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


ISimpleList

Creates an array of variants that supports enumeration.

Hierarchy

IDispatch

|--ISimpleList

Declaration

[Visual Basic]

Class CSimpleList

[C++]

interface ISimpleList : IDispatch

Members

ISimpleList defines the following properties:

Property | Description
Count | Contains the number of elements in the ISimpleList object.
Item | Contains a container for an element of the ISimpleList object.

ISimpleList defines the following methods:

Method | Description
Add | Adds the specified item to the ISimpleList object.
Delete | Deletes the specified item from the ISimpleList object.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Add Method

Adds the specified item to the ISimpleList object.

Member List

ISimpleList

|--Add

|--Count

|--Delete

|--Item

Method Declaration

[Visual Basic]

Sub Add( _

Var As Variant _

)

[C++]

HRESULT Add(

VARIANT* Var

);

Parameters

Var

[in] Contains the object to add to the ISimpleList object.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Count Property

Contains the number of elements in the ISimpleList object.

Member List

ISimpleList

|--Add

|--Count

|--Delete

|--Item

Property Declaration

[Visual Basic]

Property Count As Long

[C++]

HRESULT get_Count(

long* Count

);

Parameters

Count

[out, retval] Contains the number of items in the ISimpleList object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of items in the ISimpleList object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property is read-only with no default value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Delete Method

Deletes the specified item from the ISimpleList object.

Member List

ISimpleList

|--Add

|--Count

|--Delete

|--Item

Method Declaration

[Visual Basic]

Sub Delete( _

Index As Long _

)

[C++]

HRESULT Delete(

long Index

);

Parameters

Index

[in] Contains the index value of the item to delete.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Item Property

Contains a container for an element of the ISimpleList object.

Member List

ISimpleList

|--Add

|--Count

|--Delete

|--Item

Property Declaration

[Visual Basic]

Property Item( _

Index (ISimpleList, Item) As Long _

) As Variant

[C++]

HRESULT get_Item(

long Index (ISimpleList, Item),

VARIANT* Item (ISimpleList, Item)

);

HRESULT put_Item(

long Index,

VARIANT Item

);

HRESULT putref_Item(

long Index,

VARIANT Item

);

Parameters

Index

[in], [in] In C++, contains the index of the item.

Item

[out, retval], [in] In C++, contains the object used to return the item. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the object used to return the item.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property has no default value. The Item property is a read/write Variant that contains an element of the ISimpleList object. An initialized Variant is stored at a specified array index. If an item is already stored at the specified index, that item is overwritten by the put method.

In C++, When putting a value, use the putref_Item method if you are setting an object reference; use the put_Item method if you are setting a scalar value.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: commerce.h
Library: Microsoft Commerce 2000 Core Components Type Library (MscsCore.dll)


Enumerations

The following enumerations provide possible property and parameter values:

  • BIZTALK_CONFIGDATA_TYPE

  • BIZTALK_ENCODING_TYPE

  • BIZTALK_ENCRYPTION_TYPE

  • BIZTALK_OPENNESS_TYPE

  • BIZTALK_OPENNESS_TYPE_EX

  • BIZTALK_SIGNATURE_TYPE

  • BIZTALK_STORE_TYPE

  • BIZTALK_TRANSPORT_TYPE

  • BIZTALK_USAGE_TYPE


BIZTALK_CONFIGDATA_TYPE

Configures messaging ports.

[Visual Basic]

Enum BIZTALK_CONFIGDATA_TYPE

[C++]

enum BIZTALK_CONFIGDATA_TYPE

Members

BIZTALK_CONFIGDATA_TYPE_PRIMARYTRANSPORT

[0] Configures the primary transport on the messaging port.

BIZTALK_CONFIGDATA_TYPE_SECONDARYTRANSPORT

[1] Configures the secondary transport on the messaging port.

BIZTALK_CONFIGDATA_TYPE_ENCRYPTION

[2] Configures the encryption certificate on the messaging port.

BIZTALK_CONFIGDATA_TYPE_ENCODING

[2] Configures the encoding type on the messaging port.

BIZTALK_CONFIGDATA_TYPE_SIGNATURE

[4] Configures the signature verification on the messaging port.

BIZTALK_CONFIGDATA_TYPE_SERIALIZER

[5] Configures the serializer on the messaging port.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

GetConfigComponent

GetConfigData

SetConfigComponent

SetConfigData

Using Custom Components


BIZTALK_ENCODING_TYPE

Specifies the encoding type.

[Visual Basic]

Enum BIZTALK_ENCODING_TYPE

[C++]

enum BIZTALK_ENCODING_TYPE

Members

BIZTALK_ENCODING_TYPE_NONE

[1] Specifies that encoding is not used.

BIZTALK_ENCODING_TYPE_MIME

[2] Specifies Multipurpose Internet Mail Extensions (MIME) encoding.

BIZTALK_ENCODING_TYPE_CUSTOM

[3] Specifies custom encoding.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

EncodingType


BIZTALK_ENCRYPTION_TYPE

Specifies the encryption type.

[Visual Basic]

Enum BIZTALK_ENCRYPTION_TYPE

[C++]

enum BIZTALK_ENCRYPTION_TYPE

Members

BIZTALK_ENCRYPTION_TYPE_NONE

[1] Specifies that encryption is not used.

BIZTALK_ENCRYPTION_TYPE_CUSTOM

[2] Specifies custom encryption.

BIZTALK_ENCRYPTION_TYPE_SMIME

[4] Specifies Secure Multipurpose Internet Mail Extensions (S/MIME) encryption.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

EncryptionType


BIZTALK_OPENNESS_TYPE

Specifies the openness type.

[Visual Basic]

Enum BIZTALK_OPENNESS_TYPE

[C++]

enum BIZTALK_OPENNESS_TYPE

Members

BIZTALK_OPENNESS_TYPE_NOTOPEN

[1] Specifies that this instance of the object is not open.

BIZTALK_OPENNESS_TYPE_SOURCE

[2] Specifies that the source organization of this instance of the object is open.

BIZTALK_OPENNESS_TYPE_DESTINATION

[4] Specifies that the destination organization of this instance of the object is open.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: (cisapi.tlb)

Related Topics

Openness

Submit

SubmitSync


BIZTALK_OPENNESS_TYPE_EX

Specifies the openness type.

[Visual Basic]

Enum BIZTALK_OPENNESS_TYPE_EX

[C++]

enum BIZTALK_OPENNESS_TYPE_EX

Members

BIZTALK_OPENNESS_TYPE_EX_NOTOPEN

[1] Specifies that this instance of the object is not open.

BIZTALK_OPENNESS_TYPE_EX_SOURCE

[2] Specifies that the source organization of this instance of the object is open.

BIZTALK_OPENNESS_TYPE_EX_DESTINATION

[4] Specifies that the destination organization of this instance of the object is open.

BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW

[8] Specifies that BizTalk Server is receiving a document from an XLANG schedule instance.

BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW

[16] Specifies that BizTalk Server is sending a document to an XLANG schedule instance.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Openness


BIZTALK_SIGNATURE_TYPE

Specifies the signature type.

[Visual Basic]

Enum BIZTALK_SIGNATURE_TYPE

[C++]

enum BIZTALK_SIGNATURE_TYPE

Members

BIZTALK_SIGNATURE_TYPE_NONE

[1] Specifies that there is no signature.

BIZTALK_SIGNATURE_TYPE_CUSTOM

[2] Specifies the custom signature of the document.

BIZTALK_SIGNATURE_TYPE_SMIME

[4] Specifies the S/MIME signature of the document.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

SignatureType


BIZTALK_STORE_TYPE

Specifies the store type of the certificate.

[Visual Basic]

Enum BIZTALK_STORE_TYPE

[C++]

enum BIZTALK_STORE_TYPE

Members

BIZTALK_STORE_TYPE_MY

[1] Specifies that the certificate store is type MY. This store contains certificates authorized only by your organization.

BIZTALK_STORE_TYPE_BIZTALK

[2] Specifies that the certificate is stored in the dedicated BizTalk Server 2002 store.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Certificates

Store


BIZTALK_TRANSPORT_TYPE

Specifies the transport component type.

[Visual Basic]

Enum BIZTALK_TRANSPORT_TYPE

[C++]

enum BIZTALK_TRANSPORT_TYPE

Members

BIZTALK_TRANSPORT_TYPE_NONE

[1] Specifies that this instance of the object does not select a transport component.

BIZTALK_TRANSPORT_TYPE_HTTP

[4] Specifies that this instance of the object selects a Hypertext Transfer Protocol (HTTP) transport component.

BIZTALK_TRANSPORT_TYPE_SMTP

[8] Specifies that this instance of the object selects a Simple Mail Transfer Protocol (SMTP) transport component.

BIZTALK_TRANSPORT_TYPE_APPINTEGRATION

[32] Specifies that this instance of the object selects an application integration component (AIC) transport component.

BIZTALK_TRANSPORT_TYPE_MSMQ

[128] Specifies that this instance of the object selects a Microsoft Message Queuing transport component.

BIZTALK_TRANSPORT_TYPE_FILE

[256] Specifies that this instance of the object selects a file as a transport component.

BIZTALK_TRANSPORT_TYPE_HTTPS

[1024] Specifies that this instance of the object selects a Secure Hypertext Transfer Protocol (HTTPS) transport component.

BIZTALK_TRANSPORT_TYPE_OPENDESTINATION

[2048] Specifies that the messaging port is an open destination.

BIZTALK_TRANSPORT_TYPE_LOOPBACK

[4096] Specifies that the document submitted to the server with the SubmitSync method will be processed and then returned back as the response document of the method.

BIZTALK_TRANSPORT_TYPE_ORCHESTRATIONACTIVATION

[8192] Specifies that the Address property contains the path of an XLANG schedule to be executed.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Type


BIZTALK_USAGE_TYPE

Specifies the usage type of the certificate.

[Visual Basic]

Enum BIZTALK_USAGE_TYPE

[C++]

enum BIZTALK_USAGE_TYPE

Members

BIZTALK_USAGE_TYPE_ENCRYPTION

[1] Specifies that this is an encryption certificate.

BIZTALK_USAGE_TYPE_SIGNATURE

[2] Specifies that this is a signature certificate.

BIZTALK_USAGE_TYPE_BOTH

[4] Specifies that this certificate is used for both encryption and signature.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BizTalkObjectModel.h
Library: Microsoft BizTalk Server Configuration Objects 1.0 Type Library (BizTalkObjectModel.dll)

Related Topics

Certificates

Usage


Documents Reference

This section provides reference information about application programming interfaces (APIs) used by Microsoft BizTalk Server 2002 for both C++ and Microsoft Visual Basic programming.

Reference information is provided for all interfaces, methods, properties, and enumerations exposed for working with documents:

  • Interfaces

  • Enumerations

In addition, a complete list of Error Messages is provided.


Interfaces

The following COM interfaces are documented:

  • IBizTalkTrackData

  • IBTSCustomProcess

  • IBTSCustomProcessContext

  • IInterchange


IBizTalkTrackData Interface

Use this object to facilitate programmatic access to the tracking information of Microsoft BizTalk Server 2002. This object complements the IInterchange object so that returns from IInterchange methods can be passed to these methods for reading tracking data about the documents submitted to BizTalk Server 2002.

Hierarchy

IDispatch

|--IBizTalkTrackData

Declaration

[Visual Basic]

Class BTSDocTracking

[C++]

interface IBizTalkTrackData : IDispatch

Members

IBizTalkTrackData defines the following methods:

Method | Description
GetInDocDetails | Returns an ADO recordset that contains a list of the documents that were submitted to BizTalk Server by using the Submit method.
GetInterchanges | Returns an ADO recordset that contains a list of interchanges that were submitted to BizTalk Server by using the Submit method, including all the data from the Tracking database.
GetOutDocDetails | Returns an ADO recordset that contains a list of the documents that were generated as a result of the Submit method.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

Understanding the Tracking Database Schema

Document Definitions

Reading the Tracking Database

Document Tracking


GetInDocDetails Method

Returns an ADO recordset that contains a list of the documents that were submitted to BizTalk Server by using the Submit method.

Member List

IBizTalkTrackData

|--GetInDocDetails

|--GetInterchanges

|--GetOutDocDetails

Method Declaration

[Visual Basic]

Function GetInDocDetails( _

SubmissionID As String _

) As Object

[C++]

HRESULT GetInDocDetails(

BSTR SubmissionID ,

IDispatch** Result

);

Parameters

SubmissionID

[in] Contains the SubmissionHandle string returned by Submit for this document instance.

Result

[out, retval] In C++, an IDispatch interface that contains a list of the documents that were included in the submission. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns an Object that contains a list of the documents that were included in the submission.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method returns specific information for an input document.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

Understanding the Tracking Database Schema


GetInterchanges Method

Returns an ADO recordset that contains a list of interchanges that were submitted to BizTalk Server by using the Submit method, including all the data from the Tracking database.

Member List

IBizTalkTrackData

|--GetInDocDetails

|--GetInterchanges

|--GetOutDocDetails

Method Declaration

[Visual Basic]

Function GetInterchanges( _

SubmissionID As String _

) As Object

[C++]

HRESULT GetInterchanges(

BSTR SubmissionID ,

IDispatch** Result

);

Parameters

SubmissionID

[in] Contains the SubmissionHandle string returned by Submit for this interchange.

Result

[out, retval] In C++, an IDispatch interface that contains a list of the interchanges that were included in the submission, including all the data from the Tracking database. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method optionally returns an Object that contains a list of interchanges contained in this submission, including all the data from the Tracking database.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

You can check the Tracking database to confirm or check status on delivery because transport-specific information, such as delivery times and receipt flags, appears in the Tracking database.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

Understanding the Tracking Database Schema


GetOutDocDetails Method

Returns an ADO recordset that contains a list of the documents that were generated as a result of the Submit method.

Member List

IBizTalkTrackData

|--GetInDocDetails

|--GetInterchanges

|--GetOutDocDetails

Method Declaration

[Visual Basic]

Function GetOutDocDetails( _

SubmissionID As String _

) As Object

[C++]

HRESULT GetOutDocDetails(

BSTR SubmissionID ,

IDispatch** Result

);

Parameters

SubmissionID

[in] Contains the SubmissionHandle string returned by Submit for this document instance.

Result

[out, retval] In C++, an IDispatch interface that contains a list of the documents that were generated as a result of the submission. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns an Object that contains a list of the documents that were generated as a result of the submission.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method returns specific information for an output document, for example, PO #123456 from a Submit call made on a specific date.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

Understanding the Tracking Database Schema


IBTSCustomProcess

Implement IBTSCustomProcess to create a custom preprocessor for BizTalk Server receive functions.

Hierarchy

IUnknown

|--IBTSCustomProcess

Declaration

[Visual Basic]

Class IBTSCustomProcess

[C++]

interface IBTSCustomProcess : IUnknown

Members

IBTSCustomProcess defines the following methods:

Method | Description
Execute | Performs the custom processing on data obtained from a receive function.
SetContext | Retrieves context information associated with the data being processed.

Remarks

For information about custom preprocessors, see Preprocessing Documents in a Receive Function.

Custom preprocessor components must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Preprocessor components register themselves with the category ID CATID_BIZTALK_CUSTOM_PROCESS. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


Execute Method

Performs the custom processing on data obtained from a receive function.

Member List

IBTSCustomProcess

|--Execute

|--SetContext

Method Declaration

[Visual Basic]

Sub Execute( _

DataIn As Variant, _

CodePageIn As Long, _

IsFilePath As Boolean, _

CodePageOut As Variant, _

DataOut As Variant _

)

[C++]

HRESULT NAME(

VARIANT DataIn,

long CodePageIn,

VARIANT_BOOL IsFilePath,

VARIANT* CodePageOut,

VARIANT* DataOut

);

Parameters

DataIn

[in] In Visual Basic, contains the input data read by the receive function. For data read from a message queue, the data can be either an array or a String. If the data is read from a file receive function, this parameter contains the file path. For file receive functions, the IsFilePath parameter is set to True.

[in] In C++, contains the input data read by the receive function. For data read from a message queue, the data can be either an array or a BSTR. If the data is read from a file receive function, this parameter contains the file path. For file receive functions, the IsFilePath parameter is set to VARIANT_TRUE.

CodePageIn

[in] Contains the code page of the input data. The code page indicates the character set and keyboard layout used on a computer.

IsFilePath

[in] In Visual Basic, contains a value that indicates whether or not the DataIn parameter contains a file path. True indicates that the DataIn parameter contains a file path; False indicates that the DataIn parameter contains data from a message queue receive function.

[in] In C++, contains a value that indicates whether or not the DataIn parameter contains a file path. VARIANT_TRUE indicates that the DataIn parameter contains a file path; VARIANT_FALSE indicates that the DataIn parameter contains data from a message queue receive function.

CodePageOut

[in, out] Contains the code page of the output data. The code page indicates the character set and keyboard layout used on a computer.

DataOut

[in, out] In Visual Basic, contains the output data. For file receive functions, this will be a String. The data in this parameter is sent to BizTalk Server for processing.

[in, out] In C++, contains the output data. For file receive functions, this will be a BSTR. The data in this parameter is sent to BizTalk Server for processing.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

If BizTalk Server fails to create the custom preprocessor component, or if the Execute method returns an error or invalid data, the document being processed is placed in the Suspended queue.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


SetContext Method

Retrieves information associated with a document submitted to BizTalk Server.

Member List

IBTSCustomProcess

|--Execute

|--SetContext

Method Declaration

[Visual Basic]

Sub SetContext( _

Ctx As IBTSCustomProcessContext _

)

[C++]

HRESULT SetContext(

IBTSCustomProcessContext* Ctx

);

Parameters

Ctx

[in] IBTSCustomProcessContext that contains information associated with the document being processed by BizTalk Server.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

For additional information about the custom process context object, see IBTSCustomProcessContext.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


IBTSCustomProcessContext

Retrieves information associated with data being processed by using a custom preprocessor component.

Hierarchy

IUnknown

|-- IBTSCustomProcessContext

Declaration

[Visual Basic]

Class IBTSCustomProcessContext

[C++]

interface IBTSCustomProcessContext: IUnknown

Members

IBTSCustomProcessContext defines the following properties:

Property | Description
ChannelName | Contains the name of the channel.used for processing the current document.
DestID | Contains the value of the destination organization qualifier.
DestQualifier | Contains the destination organization qualifier type.
DocName | Contains the name of the document definition used by the current document.
EnvelopeName | Contains the name of the envelope used with the current document.
Openness | Contains the openness value associated with the messaging port.
PassThrough | Contains a value indicating whether the document uses pass-through submission mode.
SourceID | Contains the value of the source organization qualifier.
SourceQualifier | Contains the source organization qualifier type.

Remarks

This object can be obtained by calling the SetContext method on the IBTSCustomProcess object. For information about custom preprocessors, see Preprocessing Documents in a Receive Function.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


ChannelName Property

Contains the name of the channel used for processing the current document.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property ChannelName As String

[C++]

HRESULT get_ChannelName(

BSTR* ChannelName

);

Parameters

ChannelName

[out, retval] In C++, contains the name of the channel used for processing the current document. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the channel.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


DestID Property

Contains the value of the destination organization qualifier.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property DestID As String

[C++]

HRESULT get_DestID(

BSTR* DestID

);

Parameters

DestID

[out, retval] In C++, contains the value of the destination organization qualifier. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the destination organization qualifier.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


DestQualifier Property

Contains the destination organization qualifier type.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property DestQualifier As String

[C++]

HRESULT get_DestQualifier(

BSTR* DestQualifier

);

Parameters

DestQualifier

[out, retval] In C++, contains the value of the destination organization type. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the destination organization qualifier type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


DocName Property

Contains the name of the document definition used by the current document.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property DocName As String

[C++]

HRESULT get_DocName(

BSTR* DocName

);

Parameters

DocName

[out, retval] In C++, contains the document definition name. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the document definition.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


EnvelopeName Property

Contains the name of the envelope used with the current document.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property EnvelopeName As String

[C++]

HRESULT get_EnvelopeName(

BSTR* EnvName

);

Parameters

EnvName

[out, retval] In C++, contains the envelope name. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the envelope.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


Openness Property

Contains the openness value associated with the messaging port.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property Openness As Long

[C++]

HRESULT get_Openness(

long* Openness

);

Parameters

Openness

[out, retval] In C++, indicates the openness on the messaging port. Valid values for this parameter are defined by the BIZTALK_OPENNESS_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value from the BIZTALK_OPENNESS_TYPE enumeration.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


PassThrough Property

Contains a value indicating whether the document uses pass-through submission mode.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property PassThrough As Long

[C++]

HRESULT get_PassThrough(

long* PassThrough

);

Parameters

PassThrough

[out, retval] In C++, indicates whether the document uses pass-through submission mode. A value of 0 indicates that pass-through submission mode is not used. A non-zero value indicates that pass-through submission mode is used with the current document. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether the document uses pass-through submission mode. A value of 0 indicates that pass-through submission mode is not used. A non-zero value indicates that pass-through submission mode is used with the current document.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


SourceID Property

Contains the value of the source organization qualifier.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property SourceID As String

[C++]

HRESULT get_SourceID(

BSTR* SourceID

);

Parameters

SourceID

[out, retval] In C++, contains the value of the source organization qualifier. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the source organization qualifier.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


SourceQualifier Property

Contains the source organization qualifier type.

Member List

IBTSCustomProcessContext

|--ChannelName

|--DestID

|--DestQualifier

|--DocName

|--EnvelopeName

|--Openness

|--PassThrough

|--SourceID

|--SourceQualifier

Property Declaration

[Visual Basic]

Property SourceQualifier As String

[C++]

HRESULT get_SourceQualifier(

BSTR* SourceQualifier

);

Parameters

SourceQualifier

[out, retval] In C++, contains the value of the source organization type. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the source organization qualifier type.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


IInterchange

Use this object to exchange documents between applications and BizTalk Server 2002 directly or through a receive function

Hierarchy

IDispatch

|--IInterchange

Declaration

[Visual Basic]

Class Interchange

[C++]

interface IInterchange : IDispatch

Members

IInterchange defines the following methods:

Method | Description
CheckSuspendedQueue | Returns a list of documents from the Suspended queue that match the request criteria.
DeleteFromSuspendedQueue | Deletes all specified documents from the Suspended queue.
GetSuspendedQueueItemDetails | Retrieves information about a single entry in the Suspended queue.
Submit | Sends an interchange or document to BizTalk Server 2002 for asynchronous processing. BizTalk Server 2002 places the document in a queue until the next available server can process it.
SubmitSync | Sends an interchange or document to BizTalk Server 2002 for synchronous processing. An optional response document is returned to the caller.

Remarks

Using parameters with Submit and SubmitSync overrides certain fields in the header of a self-routing document.

For information about submitting documents from a remote client, see How To.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Direct Integration

Submitting

Routing

Submitting Documents

Submitting a Document


CheckSuspendedQueue Method

Returns a list of documents from the Suspended queue that match the request criteria.

Member List

IInterchange

|--CheckSuspendedQueue

|--DeleteFromSuspendedQueue

|--GetSuspendedQueueItemDetails

|--Submit

|--SubmitSync

Method Declaration

[Visual Basic]

Function CheckSuspendedQueue( _

DocName As String, _

SourceName As String, _

DestName As String_

)

[C++]

HRESULT CheckSuspendedQueue(

BSTR DocName,

BSTR SourceName,

BSTR DestName,

VARIANT* DocumentHandleList

);

Parameters

DocName

[in] Contains the name of the IBizTalkDocument object. This parameter narrows the search for items in the Suspended queue. If this parameter is omitted, this method matches all IBizTalkDocument objects. This is an optional parameter.

SourceName

[in] Contains the name of the source IBizTalkOrganization object. This parameter narrows the search criteria for items in the Suspended queue. If this parameter is omitted, this method matches all IBizTalkOrganization objects. This is an optional parameter.

DestName

[in] Contains the name of the destination IBizTalkOrganization object. This parameter narrows the search criteria for items in the Suspended queue. If this parameter is omitted, this method matches all IBizTalkOrganization objects. This is an optional parameter.

DocumentHandleList

[out, retval] In C++, contains a list of handles to all documents in the Suspended queue. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a list of handles to all documents in the Suspended queue.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The returned items are not deleted from the queue. To delete items from the Suspended queue, use the DeleteFromSuspendedQueue method.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Submitting

Submitting a Document


DeleteFromSuspendedQueue Method

Deletes all specified documents from the Suspended queue.

Member List

IInterchange

|--CheckSuspendedQueue

|--DeleteFromSuspendedQueue

|--GetSuspendedQueueItemDetails

|--Submit

|--SubmitSync

Method Declaration

[Visual Basic]

Sub DeleteFromSuspendedQueue( _

DocumentHandleList As Variant _

)

[C++]

HRESULT DeleteFromSuspendedQueue(

VARIANT* DocumentHandleList

);

Parameters

DocumentHandleList

[in] Contains a full list of handles or a subset for documents to be deleted from the Suspended queue.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Submitting

Submitting a Document


GetSuspendedQueueItemDetails Method

Retrieves information about a single entry in the Suspended queue.

Member List

IInterchange

|--CheckSuspendedQueue

|--DeleteFromSuspendedQueue

|--GetSuspendedQueueItemDetails

|--Submit

|--SubmitSync

Method Declaration

[Visual Basic]

Sub GetSuspendedQueueItemDetails( _

ItemHandle As String, _

SourceName As Variant, _

DestName As Variant, _

DocName As Variant, _

ReasonCode As Variant, _

ItemData As Variant

)

[C++]

HRESULT GetSuspendedQueueItemDetails(

BSTR ItemHandle,

VARIANT* SourceName,

VARIANT* DestName,

VARIANT* DocName,

VARIANT* ReasonCode,

VARIANT* ItemData

);

Parameters

ItemHandle

[in] Contains the handle of an item in the Suspended queue. This value can be obtained by calling the CheckSuspendedQueue method.

SourceName

[out] Contains the name of the source IBizTalkOrganization object.

DestName

[out] Contains the name of the destination IBizTalkOrganization object.

DocName

[out] Contains the name of the IBizTalkDocument object.

ReasonCode

[out] Contains the reason a document or interchange has been placed in the Suspended queue. For more information about this value, see the CISReasonToQueue enumeration.

ItemData

[out] Contains the document instance or interchange.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Submitting

Submitting a Document


Submit Method

Sends an interchange or document to BizTalk Server 2002 for asynchronous processing. BizTalk Server 2002 places the document in a queue until the next available server can process it.

Member List

IInterchange

|--CheckSuspendedQueue

|--DeleteFromSuspendedQueue

|--GetSuspendedQueueItemDetails

|--Submit

|--SubmitSync

Method Declaration

[Visual Basic]

Function Submit( _

Openness As BIZTALK_OPENNESS_TYPE, _

Document As String, _

DocName As String, _

SourceQualifier As String, _

SourceID As String, _

DestQualifier As String, _

DestID As String, _

ChannelName As String, _

FilePath As String, _

EnvelopeName As String, _

PassThrough As Long

) As String

[C++]

HRESULT Submit(

BIZTALK_OPENNESS_TYPE Openness,

BSTR Document,

BSTR DocName,

BSTR SourceQualifier,

BSTR SourceID,

BSTR DestQualifier,

BSTR DestID,

BSTR ChannelName,

BSTR FilePath,

long EnvelopeName,

BSTR* PassThrough,

BSTR* SubmissionHandle

);

Parameters

Openness

[in] Indicates whether associated IBizTalkPort objects can be open. Valid values are defined by the BIZTALK_OPENNESS_TYPE enumeration.

Document

[in] Contains the document instance submitted. This parameter accepts only a string buffer as the document or interchange. This means that applications cannot submit other objects, such as DOM objects, IDictionary objects, ADO objects, or any other data type or object type. Either the Document parameter or the FilePath parameter must be specified. Do not specify both. This is an optional parameter.

DocName

[in] Contains the name of the IBizTalkDocument object associated with the instance of the document being submitted. If the Openness parameter is set to BIZTALK_OPENNESS_TYPE_SOURCE, you can select an input IBizTalkDocument object that has an X12 or EDIFACT specification. If you do, however, the output IBizTalkDocument must not have an X12 or EDIFACT specification. If Openness is set to BIZTALK_OPENNESS_TYPE_DESTINATION, the IBizTalkDocument object must not have an X12 or EDIFACT specification. The DocName parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

SourceQualifier

[in] Contains the qualifier of the source organization. This indicates how the SourceID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the Data Universal Numbering System (D-U-N-S) number, telephone number, and BizTalk. You must specify a SourceID. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. The SourceQualifier parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

SourceID

[in] Contains the value of the qualifier of the source organization. For example, if the SourceQualifier parameter is Telephone, this value is the telephone number. If the Openness flag is set to OpenSrc, SourceID is interpreted as the source organization name. The SourceID parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

DestQualifier

[in] Contains the qualifier of the destination organization. This indicates how the DestID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the D-U-N-S number, telephone number, and BizTalk. You must specify a DestID. The default qualifier for all new organizations is OrganizationName and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. The DestQualifier parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

DestID

[in] Contains the value of the qualifier of the destination organization. For example, if the DestQualifier parameter is Telephone, this value is the telephone number. If the Openness flag is set to OpenDest, DestID is used as the destination address. Note that the queue:// prefix must be used with an open messaging port when a Message Queue is specified as the destination address. The DestID parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

ChannelName

[in] Contains the name of the IBizTalkChannel object that is executed for this document. This bypasses the normal processing in which the parser tries to determine which messaging port/channel pair to execute, based on routing information in the parameters or in the document. This is an optional parameter unless the PassThrough parameter is set to TRUE.

FilePath

[in] Specifies a fully qualified path that contains the document to be submitted, rather than submitting the document directly as a string. BizTalk Server 2002 supports URL, UNC, and drive: format only. If the document is submitted as a file that is pointed to by the FilePath parameter, the call returns successfully after BizTalk Server 2002 has successfully copied the file to the Work queue. It is safe to delete the file from the specified path as soon as this method returns successfully. When a document is submitted to the server, using FilePath to specify the data, Submit can take 30 seconds or longer if the location of the file resides on a remote server that is unavailable, if the UNC path is invalid, or if the SQL server is down. Either the Document parameter or the FilePath parameter must be specified. Do not specify both. The FilePath parameter cannot be used if the PassThrough parameter is set to TRUE and a map is specified. This is an optional parameter.

EnvelopeName

[in] Contains the name of the envelope specification to use to break the interchange into documents. When an envelope name is provided in this parameter, the envelope must have a valid interchange specification. This requirement is enforced for envelopes created for Custom XML format also. When submitting a flat file to BizTalk Server 2002, you must create an envelope for this flat file and specify the name of the envelope in EnvelopeName. This is an optional parameter.

PassThrough

[in] Indicates how the server processes the document. When this parameter is set to TRUE, no decryption, decoding, or signature verification is performed on the document. When set to FALSE, the document is decrypted and decoded, and the signature is verified. When using pass-through submission mode (TRUE), the BIZTALK_OPENNESS_TYPE value must be set to BIZTALK_OPENNESS_TYPE_NOTOPEN and the ChannelName parameter must be specified. In addition, the DocName, SourceQualifier, SourceID, DestQualifier, and DestID parameters cannot be specified with pass-through submission mode. Pass-through submission mode should be used to prevent data corruption when exchanging binary files, or when only the server transport and global tracking features are being used.

SubmissionHandle

[out, retval] In C++, contains a unique identifier for the submitted document or interchange. This handle can be used to query the Tracking database for the status of the interchange or document submitted. If more than one document is submitted (an interchange), a single handle is returned, yet the Tracking database enables the user to get the status of all child documents related to this interchange identifier. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns a unique identifier for the submitted document or interchange. This handle can be used to query the Tracking database for the status of the interchange or document submitted. If more than one document is submitted (an interchange), a single handle is returned; yet the Tracking database can access the status of all child documents related to this interchange identifier.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Openness

Routing

Submitting

Submitting a Document


SubmitSync Method

Sends an interchange or document to BizTalk Server 2002 for synchronous processing. An optional response document is returned to the caller.

Member List

IInterchange

|--CheckSuspendedQueue

|--DeleteFromSuspendedQueue

|--GetSuspendedQueueItemDetails

|--Submit

|--SubmitSync

Method Declaration

[Visual Basic]

Sub SubmitSync( _

Openness As BIZTALK_OPENNESS_TYPE, _

Document As String, _

DocName As String, _

SourceQualifier As String, _

SourceID As String, _

DestQualifier As String, _

DestID As String, _

ChannelName As String, _

FilePath As String, _

EnvelopeName As String, _

PassThrough As Long, _

SubmissionHandle As Variant, _

ResponseDocument As Variant

)

[C++]

HRESULT SubmitSync(

BIZTALK_OPENNESS_TYPE Openness,

BSTR Document,

BSTR DocName,

BSTR SourceQualifier,

BSTR SourceID,

BSTR DestQualifier,

BSTR DestID,

BSTR ChannelName,

BSTR FilePath,

long EnvelopeName,

BSTR* PassThrough,

VARIANT* SubmissionHandle,

VARIANT* ResponseDocument

);

Parameters

Openness

[in] Indicates whether associated IBizTalkPort objects can be open. Valid values are defined by the BIZTALK_OPENNESS_TYPE enumeration.

Document

[in] Contains the document instance submitted. This parameter accepts only a string buffer as the document or interchange. This means that applications cannot submit other objects, such as DOM objects, IDictionary objects, ADO objects, or any other data type or object type. Either the Document parameter or the FilePath parameter must be specified. Do not specify both. This is an optional parameter.

DocName

[in] Contains the name of the IBizTalkDocument object associated with the instance of the document submitted. If the Openness parameter is set to BIZTALK_OPENNESS_TYPE_SOURCE, you can select an input IBizTalkDocument object that has an X12 or EDIFACT specification. If you do, however, the output IBizTalkDocument must not have an X12 or EDIFACT specification. If Openness is set to BIZTALK_OPENNESS_TYPE_DESTINATION, the IBizTalkDocument object must not have an X12 or EDIFACT specification. The DocName parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

SourceQualifier

[in] Contains the qualifier of the source organization. This indicates how the SourceID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the D-U-N-S number, telephone number, and BizTalk. You must specify a SourceID. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. The SourceQualifier parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

SourceID

[in] Contains the value of the qualifier of the source organization. For example, if the SourceQualifier parameter is Telephone, this value is the telephone number. If the Openness flag is set to OpenSrc, SourceID is interpreted as the source organization name. The SourceID parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

DestQualifier

[in] Contains the qualifier of the destination organization. This indicates how the DestID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the D-U-N-S number, telephone number, and BizTalk. You must specify a DestID parameter. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk. The DestQualifier parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

DestID

[in] Contains the value of the qualifier of the destination organization. For example, if the DestQualifier parameter is Telephone, this value is the telephone number. If the Openness flag is set to OpenDest, DestID is used as the destination address. Note that the queue:// prefix must be used with an open messaging port when a Message Queue is specified as the destination address. The DestID parameter cannot be used if the PassThrough parameter is set to TRUE. This is an optional parameter.

ChannelName

[in] Contains the name of the IBizTalkChannel object that is executed for this document. This bypasses the normal processing in which the parser tries to determine which messaging port/channel pair to execute, based on routing information in the parameters or in the document. This is an optional parameter unless the PassThrough parameter is set to TRUE.

FilePath

[in] Specifies a fully qualified path that contains the document to be submitted, rather than submitting the document directly as a string. BizTalk Server 2002 supports URL, UNC, and drive: format only. Either the Document parameter or the FilePath parameter must be specified. Do not specify both. The FilePath parameter cannot be used if the PassThrough parameter is set to TRUE and a map is specified. This is an optional parameter.

EnvelopeName

[in] Contains the name of the envelope specification to use to break the interchange into documents. When an envelope name is provided in this parameter, the envelope must have a valid interchange specification. This requirement is enforced for envelopes created for Custom XML format also. This is an optional parameter.

PassThrough

[in] Indicates how the server processes the document. When this parameter is set to TRUE, no decryption, decoding, or signature verification is performed on the document. When set to FALSE, the document is decrypted and decoded, and the signature is verified. When using pass-through submission mode (TRUE), the BIZTALK_OPENNESS_TYPE value must be set to BIZTALK_OPENNESS_TYPE_NOTOPEN and the ChannelName parameter must be specified. In addition, the DocName, SourceQualifier, SourceID, DestQualifier, and DestID parameters cannot be specified with pass-through submission mode. Pass-through submission mode should be used to prevent data corruption when exchanging binary files, or when only the server transport and global tracking features are being used.

SubmissionHandle

[out] Contains a unique identifier for the submitted document or interchange. This handle can be used to query the Tracking database for the status of the interchange or document submitted. If more than one document is submitted (an interchange), a single handle is returned; yet the Tracking database can access the status of all child documents related to this interchange identifier.

ResponseDocument

[out] Contains the optional response document.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

SubmitSync returns an optional response document when provided. If no response is returned, the call returns successfully, but with no response and with an HRESULT value of S_FALSE. If the destination is another BizTalk Server, an ASP page must be used to return a response.

A synchronous interchange bypasses all queues and executes all the components required by the messaging port on the calling thread. For synchronous protocols (HTTP and AIC), an optional response document is returned to the user, if available. This method is valid only for a single channel match. If the parameters set cause multiple channels to match, synchronous submission returns an error indicating that multiple channel matches are not allowed for synchronous submission. This method can be used only for single document interchanges. If the submission contains multiple documents, synchronous submission returns an error indicating that multiple document submissions are not allowed. This method does not support port groups.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

Openness

Routing

Submitting

Submitting a Document


Enumerations

The following enumeration provides possible property and parameter values:

  • CISReasonToQueue


CISReasonToQueue

Describes the reasons a document was placed in a queue.

[Visual Basic]

Enum CISReasonToQueue_tag

[C++]

enum CISReasonToQueue

Members

noReason

[0] Not supported for this release.

rtdlqParserFailure

[1] Specifies that the instance of the document was placed in the queue because of failure of the parser.

rtdlqParserDocFailure

[2] Specifies that the instance of the document was placed in the queue because the business document was invalid.

rtdlqDocValidation

[3] Specifies that the document was placed in the queue because document validation failed.

rtdlqChannelSelectFailure

[4] Specifies that the instance of the document was placed in the queue because of failure in selecting the correct IBizTalkChannel object.

rtdlqInvalidMap

[5] Specifies that the instance of the document was placed in the queue because the map referred to by the BizTalkChannel object was formatted incorrectly.

rtdlqFieldTrackingFailure

[6] Specifies that the instance of the document was placed in the queue because the server was unable to track the requested fields within the document.

rtdlqMappingFailure

[7] Specifies that the instance of the document was placed in the queue because of failure of transformation.

rtdlqSerializerFailure

[8] Specifies that the instance of the document was placed in the queue because the server could not convert this document to its native format.

rtdlqEncodingFailure

[9] Specifies that the instance of the document was placed in the queue because the server was unable to encode this interchange.

rtdlqSigningFailure

[10] Specifies that the instance of the document was placed in the queue because the server was unable to sign this interchange.

rtdlqEncryptionFailure

[11] Specifies that the instance of the document was placed in the queue because the server was unable to encrypt this interchange.

rtdlqTransmissionFailure

[12] Specifies that the instance of the document was placed in the queue because the server was unable to deliver this document.

rtdlqUserMove

[13] Specifies that the administrator moved this instance of the document to the queue.

rtdlqTimeout

[14] Specifies that the instance of the document was placed in the queue because a time-out occurred.

rtdlqCustomCompFailure

[15] Specifies that the instance of the document was placed in the queue because of failure of a custom component.

unkReason

[16] Specifies that this item was marked as "In process" by an inactive server. On restart of this server, this item was automatically moved to the Suspended queue. There was probably a catastrophic failure on the original server. Contact the system administrator for more information.

rtdlqNoChannel

[17] Specifies that the instance of the document was placed in the queue because the BizTalkChannel object was deleted.

rtdlqMissingChannel

[18] Specifies that the instance of the document was placed in the queue because the BizTalkChannel object specified by the Submit method of the IInterchange interface was not found.

rtdlqInvalidChannel

[19] Specifies that the instance of the document was placed in the queue because the BizTalkChannel object specified by the Submit method of the IInterchange interface specifies an open IBizTalkPort object. This is not permitted.

rtdlqOutOfMemory

[20] Specifies that your computer has run out of memory. Rebooting is recommended.

rtdlqBTFRecReqExpired

[21] Specifies that the document was placed in the queue because the BTF timestamp receiptRequiredBy expired.

rtdlqBTFExpiresAtExpired

[22] Specifies that the document was placed in the queue because the BTF timestamp expiresAt expired.

rtdlqCorrelationFailure

[23] Specifies that the document receipt failed.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: cisapi.h
Library: (cisapi.tlb)

Related Topics

GetSuspendedQueueItemDetails


Custom Components Reference

This section provides reference information about application programming interfaces (APIs) used by Microsoft BizTalk Server 2002 for both C++ and Microsoft Visual Basic programming.

Reference information is provided for all interfaces, methods, properties, and enumerations exposed for working with custom components:

  • Interfaces

  • Enumerations

In addition, a complete list of Error Messages is provided.


Interfaces

The following COM interfaces are documented for C++ developers:

  • IBizTalkParserComponent

  • IBizTalkSerializerComponent

The following COM interfaces are documented for both C++ and Visual Basic developers:

  • IBizTalkAcknowledge

  • IBizTalkCorrelation

  • IBTSAppIntegration

  • IFunctoid

  • IPipelineComponent

  • IPipelineComponentAdmin

  • ISchemaImporter

  • ISchemaImporterError

  • ISchemaImporterErrorProvider


IBizTalkAcknowledge

Processes receipts sent to the server.

Hierarchy

IUnknown

|--IBizTalkAcknowledge

Declaration

[Visual Basic]

Class IBizTalkAcknowledge

[C++]

interface IBizTalkAcknowledge : IUnknown

Members

IBizTalkAcknowledge defines the following methods:

Method | Description
AckDocument | Processes receipts received for documents.
AckGroup | Processes receipts received for document groups.
AckInterchange | Processes receipts received for document interchanges.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

Creating Receipt Correlator Components

How Receipts Are Logged

Understanding Receipts


AckDocument Method

Processes receipts received for documents.

Member List

IBizTalkAcknowledge

|--AckDocument

|--AckGroup

|--AckInterchange

Method Declaration

[Visual Basic]

Sub AckDocument( _

Syntax As String, _

TrackingId As String, _

AckStatus As DTA_ACK_STATUS _

)

[C++]

HRESULT AckDocument(

BSTR Syntax,

BSTR TrackingId,

DTA_ACK_STATUS AckStatus

);

Parameters

Syntax

[in] Contains the syntax of the outbound document to be acknowledged, for example, X12 or EDIFACT.

TrackingId

[in] Contains the globally unique identifier (GUID) for tracking the document. This value can be obtained from the Tracking_ID field in the dta_outdoc_details table. For more information, see Supporting the Tracking Database with Parser and Serializer Components.

AckStatus

[in] Indicates the receipt status. Valid values for this parameter are defined by the DTA_ACK_STATUS enumeration.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called only for receipts on individual documents. If the receipt needs to be mapped, a document definition that points to CanonicalReceipt.xml shipped in WebDAV must be created for the receipt.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)


AckGroup Method

Processes receipts received for document groups.

Member List

IBizTalkAcknowledge

|--AckDocument

|--AckGroup

|--AckInterchange

Method Declaration

[Visual Basic]

Sub AckGroup( _

Syntax As String, _

Version As String, _

Release As String, _

FunctionalGroupId As String, _

ControlId As String, _

SrcAppName As String, _

DestAppName As String, _

AckStatus As DTA_ACK_STATUS _

)

[C++]

HRESULT AckGroup(

BSTR Syntax,

BSTR Version,

BSTR Release,

BSTR FunctionalGroupId,

BSTR ControlId,

BSTR SrcAppName,

BSTR DestAppName,

DTA_ACK_STATUS AckStatus

);

Parameters

Syntax

[in] Contains the syntax of the outbound document to be acknowledged, for example, X12 or EDIFACT. You must use the exact strings for the following syntax types:

  • X12

  • EDIFACT

  • Custom XML

Version

[in] Contains the version of the syntax, used primarily for EDI.

Release

[in] Contains the release of the version of the syntax, used primarily for EDI.

FunctionalGroupId

[in] Contains the code for the type of documents in a group, used primarily for EDI.

ControlId

[in] Contains the unique identifier for the control number, used primarily for EDI.

SrcAppName

[in] Contains the name of the source application.

DestAppName

[in] Contains the name of the destination application.

AckStatus

[in] Indicates the receipt status. Valid values are defined by the DTA_ACK_STATUS enumeration.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called only for receipts on document groups.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)


AckInterchange Method

Processes receipts received for document interchanges.

Member List

IBizTalkAcknowledge

|--AckDocument

|--AckGroup

|--AckInterchange

Method Declaration

[Visual Basic]

Sub AckInterchange( _

Syntax As String, _

InterchangeId As String, _

Version As String, _

ControlId As String, _

SrcAliasQualifier As String, _

SrcAliasId As String, _

SrcAppName As String, _

DestAliasQualifier As String, _

DestAliasId As String, _

DestAppName As String, _

AckStatus As DTA_ACK_STATUS _

)

[C++]

HRESULT AckInterchange(

BSTR Syntax,

BSTR InterchangeId,

BSTR Version,

BSTR ControlId,

BSTR SrcAliasQualifier,

BSTR SrcAliasId,

BSTR SrcAppName,

BSTR DestAliasQualifier,

BSTR DestAliasId,

BSTR DestAppName,

DTA_ACK_STATUS AckStatus

);

Parameters

Syntax

[in] Contains the syntax of the outbound document to be acknowledged, for example, X12 or EDIFACT. You must use the exact strings for the following syntax types:

  • X12

  • EDIFACT

  • Custom XML

InterchangeId

[in] Contains the unique tracking identifier of the interchange. This value is a globally unique identifier (GUID).

Version

[in] Contains the version of the syntax, used primarily for EDI.

ControlId

[in] Contains the unique identifier for the control number, used primarily for EDI.

SrcAliasQualifier

[in] Contains the qualifier of the source organization. This indicates how the bstrSrcAliasID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the Data Universal Numbering System (D-U-N-S) number, telephone number, and BizTalk. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk.

SrcAliasId

[in] Contains the value of the qualifier of the source organization. For example, if the bstrSrcAliasQualifier parameter is Telephone, this value is the telephone number.

SrcAppName

[in] Contains the name of the source application.

DestAliasQualifier

[in] Contains the qualifier of the source organization. This indicates how the bstrDestAliasID parameter is to be interpreted. Valid values come from the organization identifier qualifiers that are created when the user creates an alias for an organization. Common qualifiers include the D-U-N-S number, telephone number, and BizTalk. The default qualifier for all new organizations is Organization Name and refers to the name of the organization in the database. If a BizTalk Framework 2.0–compliant document is submitted and a qualifier is not found during parsing, the qualifier defaults to BizTalk.

DestAliasId

[in] Contains the value of the qualifier of the source organization. For example, if the bstrDestAliasQualifier parameter is Telephone, this value is the telephone number.

DestAppName

[in] Contains the name of the destination application.

AckStatus

[in] Indicates the receipt status. Valid values are defined by the DTA_ACK_STATUS enumeration.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called only for receipts on document interchanges.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)


IBizTalkCorrelation

Creates receipt correlator components.

Hierarchy

IUnknown

|--IBizTalkCorrelation

Declaration

This interface is only supported in C++

interface IBizTalkCorrelation : IUnknown

Members

IBizTalkCorrelation defines the following method:

Method | Description
Correlate | Extracts all relevant information from the document, document group, or interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Creating Receipt Correlator Components


Correlate Method

Extracts all relevant information from the document, document group, or interchange.

Member List

IBizTalkCorrelation

|--Correlate

Method Declaration

This method is only supported in C++

HRESULT Correlate(

IUnknown* Acknowledge,

IDictionary* Dict

);

Parameters

Acknowledge

[in] An IBizTalkAcknowledge interface used to invoke and set the receipt flag.

Dict

[in] An IDictionary interface of an object that contains the receipt information.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h


IFunctoid

Creates custom mapping functions. IFunctoid defines the generic protocol for calling custom functions used by the mapping tool.

Hierarchy

IDispatch

|--IFunctoid

Declaration

[Visual Basic]

Class CannedFunctoid

[C++]

interface IFunctoid : IDispatch

Members

IFunctoid defines the following properties:

Property | Description
FunctionsCount | Contains the number of functions implemented by the functoid.
Version | Contains the version of the functoid.

IFunctoid defines the following methods:

Method | Description
GetFunctionDescripter | Retrieves information about a specific functoid.
GetFunctionParameter | Retrieves the connection-type bit flags for the specified parameter.
GetScriptBuffer | Retrieves the script code used to implement the functoid.

Remarks

Custom functoids must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Functoids register themselves with the category ID CATID_BIZTALK_MapEditFunctoids. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Each custom functoid can support multiple functions and can contain icons and names for each supported function. Function identifiers from 0 to 1000 are reserved for built-in functions in BizTalk Mapper. User-defined functions (custom functions) should use function identifiers 1001 and above.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


FunctionsCount Property

Contains the number of functions implemented by the functoid.

Member List

IFunctoid

|--FunctionsCount

|--GetFunctionDescripter

|--GetFunctionParameter

|--GetScriptBuffer

|--Version

Property Declaration

[Visual Basic]

Property FunctionsCount As Long

[C++]

HRESULT get_FunctionsCount(

long* Count

);

Parameters

Count

[out, retval] In C++, contains the number of functions implemented by the functoid. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of functions implemented by the functoid.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


GetFunctionDescripter Method

Retrieves information about a specific functoid.

Member List

IFunctoid

|--FunctionsCount

|--GetFunctionDescripter

|--GetFunctionParameter

|--GetScriptBuffer

|--Version

Method Declaration

[Visual Basic]

Function GetFunctionDescripter( _

Index As Long, _

FuncCategory As FUNC_CATEGORY, _

ScriptCategory As SCRIPT_CATEGORY, _

FuncType As FUNC_TYPE, _

Name As String, _

ToolTip As String, _

BitmapID As Long, _

ParmCount As Long _

) As Long

[C++]

HRESULT GetFunctionDescripter(

long Index,

FUNC_CATEGORY* FuncCategory,

SCRIPT_CATEGORY* ScriptCategory,

FUNC_TYPE* FuncType,

BSTR* Name,

BSTR* ToolTip,

long* BitmapID,

long* ParmCount,

FUNCID* FuncId

);

Parameters

Index

[in] Specifies the index number of the function.

FuncCategory

[in, out] Contains a value indicating the tab on the functoid palette on which the custom functoid will appear. Valid values for this parameter are defined by the FUNC_CATEGORY enumeration.

ScriptCategory

[in, out] Contains the scripting language used by the custom functoid. Valid values for this parameter are defined by the SCRIPT_CATEGORY enumeration.

FuncType

[in, out] Contains the function type information for the custom functoid. Valid values for this parameter are defined by the FUNC_TYPE enumeration.

Name

[in, out] Contains the function name.

ToolTip

[in, out] Contains the ToolTip that appears when the mouse pointer is paused over the custom functoid icon in the mapping tool.

BitmapID

[in, out] Contains a bitmap identifier of the bitmap used for the custom functoid icon displayed in the mapping tool.

ParmCount

[in, out] Contains the number of parameters implemented by the function.

FuncId

[out, retval] In C++, contains the function identifier. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the function identifier.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


GetFunctionParameter Method

Retrieves the connection-type bit flags for the specified parameter.

Member List

IFunctoid

|--FunctionsCount

|--GetFunctionDescripter

|--GetFunctionParameter

|--GetScriptBuffer

|--Version

Method Declaration

[Visual Basic]

Function GetFunctionParameter( _

FuncId As Long, _

Parameter As Long _

) As Long

[C++]

HRESULT GetFunctionParameter(

FUNCID FuncId,

long Parameter,

long* ConnectionType

);

Parameters

FuncId

[in] Contains the function identifier.

Parameter

[in] Contains the function parameter number. For output parameters, a value of -1 is used.

ConnectionType

[out, retval] In C++, contains the connection type information of the specified parameter. Valid values for this parameter are defined by the CONNECTION_TYPE enumeration. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the connection type information of the specified parameter. Valid values for this parameter are defined by the CONNECTION_TYPE enumeration.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


GetScriptBuffer Method

Retrieves the script code used to implement the functoid.

Member List

IFunctoid

|--FunctionsCount

|--GetFunctionDescripter

|--GetFunctionParameter

|--GetScriptBuffer

|--Version

Method Declaration

[Visual Basic]

Function GetScriptBuffer( _

FuncId As Long, _

InputParameters As Long _

) As String

[C++]

HRESULT GetScriptBuffer(

FUNCID FuncId,

long InputParameters,

BSTR* ScriptBuffer

);

Parameters

FuncId

[in] Contains the function identifier.

InputParameters

[in] Indicates the number of connected input parameters for the specified function.

ScriptBuffer

[out, retval] In C++, contains the script code used to implement the function. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the script code used to implement the function.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


Version Property

Contains the version of the functoid.

Member List

IFunctoid

|--FunctionsCount

|--GetFunctionDescripter

|--GetFunctionParameter

|--GetScriptBuffer

|--Version

Property Declaration

[Visual Basic]

Property Version As Long

[C++]

HRESULT get_Version(

long* Version

);

Parameters

Version

[out, retval] In C++, contains the custom functoid version. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the custom functoid version.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

If the custom functoid is modified in any way, the author should update the version number.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)


IBizTalkParserComponent

Converts a document to XML for later processing and identifies the IBizTalkChannel objects necessary to process the documents.

Hierarchy

IUnknown

|--IBizTalkParserComponent

Declaration

This interface is only supported in C++

interface IBizTalkParserComponent : IUnknown

Members

IBizTalkParserComponent defines the following methods:

Method | Description
GetGroupDetails | Gets details of the group for the Tracking database. This method is called only if there are groups in the interchange.
GetGroupSize | Gets the size of the group after all documents in the group are parsed. This method is called only if there are groups in the interchange.
GetInterchangeDetails | Gets information about the organization identifiers of the source and destination IBizTalkOrganization objects.
GetNativeDocumentOffsets | Identifies offsets from the beginning of the stream for final details about the group in the Tracking database for final logging.
GetNextDocument | Examines the data in a document and determines when to get the next document if this is not the last document.
GroupsExist | Determines whether the interchange contains groups.
ProbeInterchangeFormat | Identifies the format of the interchange.

Remarks

Custom parser components must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Parser components register themselves with the category ID CATID_BIZTALK_PARSER. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Identification

Working with Parsers

Parsers


GetGroupDetails Method

Gets details of the group for the Tracking database. This method is called only if there are groups in the interchange.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GetGroupDetails(

IDictionary* Dict

);

Parameters

Dict

[in] IDictionary interface of an object that contains details about the group. All information is returned as string types, no matter how it appears in the data.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called only if groups are detected in the interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


GetGroupSize Method

Gets the size of the group after all documents in the group are parsed. This method is called only if there are groups in the interchange.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GetGroupSize(

long* GroupSize,

BOOL* LastGroup

);

Parameters

GroupSize

[out] Contains the size of the interchange.

LastGroup

[out] Indicates whether the group is the last group in the interchange. If this parameter is set to TRUE, the next method called is GetGroupDetails for the next group in the data. If it is set to FALSE, the component is finished. When it is released, it leaves the IStream interface after the last byte it has read.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

After all documents in the group are called, the final details about the group are required. Both output parameters are added to the Tracking database for final logging.

This method is called only if there are groups in the interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


GetInterchangeDetails Method

Gets information about the organization identifiers of the source and destination IBizTalkOrganization objects.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GetInterchangeDetails(

IDictionary* Dict

);

Parameters

Dict

[in] IDictionary interface of an object that contains information about the organization identifiers of the source and destination IBizTalkOrganization objects.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The minimum sets of fields are:

Field | Description
src_id_type | Source qualifier
src_id_value | Source ID
dest_id_type | Destination qualifier
dest_id_value | Destination ID

The parameters of the Submit method of the IInterchange interface override any fields set here.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


GetNativeDocumentOffsets Method

Identifies offsets from the beginning of the stream for final details about the group in the Tracking database for final logging.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GetNativeDocumentOffsets(

BOOL SizeFromXMLDoc,

LARGE_INTEGER* StartOffset,

long* DocLength

);

Parameters

SizeFromXMLDoc

[out] Indicates whether the XML document passed in from the GetNextDocument method was used to determine the size. If this parameter is TRUE, the server fills in the StartOffset and DocLength values for the document just parsed. If this parameter is FALSE, the server ignores the values in StartOffset and DocLength.

StartOffset

[out] Contains the location of the beginning of the document. This parameter is returned if the SizeFromXMLDoc parameter is set to TRUE.

DocLength

[out] Contains the length of the document. This parameter is returned if the SizeFromXMLDoc parameter is set to TRUE.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called immediately after GetNextDocument whether or not the document is valid (as long as the parser does not return an error value). These are offsets into the IStream object relative to the beginning of the stream, not the beginning of the interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


GetNextDocument Method

Examines the data in a document and determines when to get the next document if this is not the last document.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GetNextDocument(

IDictionary* Dict,

BSTR DocSpecName,

BOOL* DocIsValid,

BOOL* LastDocument,

GeneratedReceiptLevel ReceiptGenerated,

BOOL* DocIsReceipt,

BSTR* CorrelationCompProgID

);

Parameters

Dict

[in] IDictionary interface of an object into which to set the XML instance created on parsing the current document. The parsed XML document is placed into the working_data field of the dictionary.

DocSpecName

[in] Contains the name of the BizTalk document specification used to generate the XML from the document's native format.

DocIsValid

[out] Indicates whether the document instance is valid. If it is invalid but the parser can recover from it, set this parameter to FALSE. This parameter and the LastDocument parameter are independent. Therefore, if there are no more documents and the last one is invalid, both flags are set. If the document is invalid and the parser cannot continue, it might return an error value. The server then stops at the current position of the IStream pointer. The component places the invalid data (if the parser can recover) in the working_data field for inspection by the system administrator if the document is invalid.

LastDocument

[out] Indicates whether this is the last document instance in the group or interchange. When the last document is found, the LastDocument flag is set to TRUE. If there are groups, this flag signals the last document in the group, and the GetGroupSize method is called. If there are no groups, this is the last call to get document data from the parser, and the IStream pointer is set appropriately.

ReceiptGenerated

[out] Contains the receipt status information. Valid values are defined by the GeneratedReceiptLevel enumeration.

DocIsReceipt

[out] Identifies whether or not this document is a receipt.

CorrelationCompProgID

[out] Contains the program ID for the correlation of documents.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


GroupsExist Method

Determines whether the interchange contains groups.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT GroupsExist(

BOOL* GrpsExist

);

Parameters

GrpsExist

[out, retval] Indicates whether the data format contains groups. If this parameter is set to FALSE, the GetGroupDetails and GetGroupSize methods are never called.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


ProbeInterchangeFormat Method

Identifies the format of the interchange.

Member List

IBizTalkParserComponent

|--GetGroupDetails

|--GetGroupSize

|--GetInterchangeDetails

|--GetNativeDocumentOffsets

|--GetNextDocument

|--GroupsExist

|--ProbeInterchangeFormat

Method Declaration

This interface is only supported in C++

HRESULT ProbeInterchangeFormat(

IStream* pData,

BOOL FromFile,

BSTR EnvName,

IStream* pReceiptData,

BSTR* Format

);

Parameters

pData

[in] IStream object that contains the data for the document interchange. Additional information about the IStream object is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

FromFile

[in] Contains a value that indicates whether or not the data came from the FilePath parameter of the Submit or the SubmitSync method of the IInterchange interface. TRUE indicates that the data came from the file referred to by the FilePath parameter. FALSE indicates that the data came from the Document parameter of Submit or SubmitSync as a string. If the data is from a file, no conversion is made. If the data is a string, you can use UNICODE/MBCS techniques to understand it.

EnvName

[in] Contains the name of the envelope.

pReceiptData

[in] IStream object that contains the receipt document.

Format

[out] Contains the format of the data. If the server recognizes the format, it must fill in this parameter with a non-empty string and hold on to (add a reference count to) the IStream interface because it is not given back to the component. This IStream object is read-only; it supports only the Read, Stat, and Seek methods. All other methods return E_NOTIMPL. This method should not return a failure if it does not recognize the format. It returns S_FALSE or an empty or NULL Format string. If you do not recognize the format, you do not need to move the IStream pointer back to its original position; the server resets the IStream pointer. Unless your format requires it, do not assume that the pointer is at the beginning. The pointer can be somewhere in the middle during the probing stage.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is the first method that is called by the server. If ProbeInterchangeFormat returns an error in the middle of the document list, it blocks the server from detecting more document types, even if they could be handled by a custom parser that follows the failed parser, if there are two or more custom parsers on a server. If the first custom parser fails, any document that follows is not parsed, even if the other custom parser could handle it, because the server ends the entire parsing operation at the time of the failure.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

Working with Parsers

Parsers


IBizTalkSerializerComponent

Converts a document from XML to the document's original native format.

Hierarchy

IUnknown

|--IBizTalkSerializerComponent

Declaration

This interface is only supported in C++

interface IBizTalkSerializerComponent : IUnknown

Members

IBizTalkSerializerComponent defines the following methods:

Method | Description
AddDocument | Adds an XML document for storage by the serializer component.
GetDocInfo | Gets details of the document.
GetGroupInfo | Gets details of the group, such as size and offset, for the Tracking database.
GetInterchangeInfo | Gets information about the interchange created.
Init | Outputs the document instance to the serializer component and indicates where it should be sent.

Remarks

Custom serializer components must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Serializer components register themselves with the category ID CATID_BIZTALK_SERIALIZER. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Working with Serializers

Serializers


AddDocument Method

Adds an XML document for storage by the serializer component.

Member List

IBizTalkSerializerComponent

|--AddDocument

|--GetDocInfo

|--GetGroupInfo

|--GetInterchangeInfo

|--Init

Method Declaration

This interface is only supported in C++

HRESULT AddDocument(

long DocHandle,

IDictionary* Transport,

BSTR TrackID,

long ChannelID

);

Parameters

DocHandle

[in] Contains the handle to the document that is stored by the component and later retrieved when calling the GetDocInfo method. This parameter supports out-of-order recreation of the interchange in case the documents need to be reordered (such as in X12).

Transport

[in] Contains an IDictionary interface of an object that contains the XML document to be stored. It is on the working_data field. This parameter cannot be set by the component. This is an optional parameter.

TrackID

[in] Contains the document tracking ID used by the server.

ChannelID

[in] Contains the IBizTalkChannel object associated with the current document.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called only once per interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Working with Serializers

Serializers


GetDocInfo Method

Gets details of the document.

Member List

IBizTalkSerializerComponent

|--AddDocument

|--GetDocInfo

|--GetGroupInfo

|--GetInterchangeInfo

|--Init

Method Declaration

This interface is only supported in C++

HRESULT GetDocInfo(

long* DocHandle,

BOOL* SizeFromXMLDoc,

LARGE_INTEGER* DocStartOffset,

long* DocLen

);

Parameters

DocHandle

[out] Contains the document handle. For each ID that is passed back, this address is assigned to the group record that was created when the GetGroupInfo method was called. This parameter also returns properties of the document, for example, size and length, unless the SizeFromXMLDoc parameter is set to TRUE, in which case the other parameters are ignored.

SizeFromXMLDoc

[out] Indicates that the document offset and length values are retrieved from the XML document. TRUE indicates that the server fills in the DocStartOffset and DocLen values for the document; FALSE indicates that the server ignores the values in DocStartOffset and DocLen.

DocStartOffset

[out] Contains the offset to the beginning of the document. This parameter is returned if SizeFromXMLDoc is set to TRUE.

DocLen

[out] Contains the length of the document. This parameter is returned if SizeFromXMLDoc is set to TRUE.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called once for every document in a group (or interchange, if there are no groups).

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Working with Serializers

Serializers


GetGroupInfo Method

Gets details of the group, such as size and offset, for the Tracking database.

Member List

IBizTalkSerializerComponent

|--AddDocument

|--GetDocInfo

|--GetGroupInfo

|--GetInterchangeInfo

|--Init

Method Declaration

This interface is only supported in C++

HRESULT GetGroupInfo(

long* NumDocs,

LARGE_INTEGER* GrpStartOffset,

long* GrpLen

);

Parameters

NumDocs

[out] Contains the number of documents in the group.

GrpStartOffset

[out] Contains the offset to the start of the group in the IStream interface.

GrpLen

[out] Contains the length of the group.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called the number of times returned by the GetInterchangeInfo method. Call the GetDocInfo method for each document in the group.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Sequence for Calling Methods of the IBizTalkSerializerComponent Interface

Serializers


GetInterchangeInfo Method

Gets information about the interchange created.

Member List

IBizTalkSerializerComponent

|--AddDocument

|--GetDocInfo

|--GetGroupInfo

|--GetInterchangeInfo

|--Init

Method Declaration

This interface is only supported in C++

HRESULT GetInterchangeInfo(

BSTR* InterchangeID,

long* NumGroups

);

Parameters

InterchangeID

[out] Contains the interchange ID, which is placed in the Tracking database.

NumGroups

[out] Contains the number of groups generated in the interchange. This value can be either 0 or 1. A document can exist in only one group.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is called after all the documents are passed in.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Working with Serializers

Serializers


Init Method

Outputs the document instance to the serializer component and indicates its destination.

Member List

IBizTalkSerializerComponent

|--AddDocument

|--GetDocInfo

|--GetGroupInfo

|--GetInterchangeInfo

|--Init

Method Declaration

This interface is only supported in C++

HRESULT Init(

BSTR srcQual,

BSTR srcID,

BSTR destQual,

BSTR destID,

long envID,

IDictionary* Delimiters,

Istream* OutputStream,

long NumDocs

);

Parameters

srcQual

[in] Contains the source-organization identifier qualifier.

srcID

[in] Contains the source-organization identifier value.

destQual

[in] Contains the destination-organization identifier qualifier.

destID

[in] Contains the destination-organization identifier value.

EnvID

[in] Contains the envelope identifier value.

Delimiters

[in] Contains an IDictionary interface of an object that contains the delimiters used in the document.

OutputStream

[in] Contains an IStream interface that contains the data of this document. This IStream pointer is write-only. The only methods that are supported are Write and Stat; all other methods return E_NOTIMPL. Additional information about the IStream object is available on the Microsoft Developer Network at msdn.microsoft.com/library/default.asp.

NumDocs

[in] Contains the number of documents sent as part of this interchange. For this release, this parameter is set to 1.

Return Values

This method returns an HRESULT value, indicating success or failure.

Error Handling

If the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSSerializerComps.h

Related Topics

Working with Serializers

Serializers


IBTSAppIntegration

Creates an entry point for receiving a document.

Hierarchy

IDispatch

|--IBTSAppIntegration

Declaration

[Visual Basic]

Class IBTSAppIntegration

[C++]

interface IBTSAppIntegration : IDispatch

Members

IBTSAppIntegration defines the following method:

Method | Description
ProcessMessage | Processes a document and returns a response document, if available. This method is called at run time when the server is sending a document to the component.

Remarks

Application integration components must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Application integration components register themselves with the category ID CATID_BIZTALK_AIC. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)

Related Topics

Lightweight Application Integration Components

Application Integration in Visual Basic

Application Integration in Visual C++


ProcessMessage Method

Processes a document and returns a response document, if available. This method is called at run time when the server is sending a document to the component.

Member List

IBTSAppIntegration

|--ProcessMessage

Method Declaration

[Visual Basic]

Function ProcessMessage( _

Document As String _

) As String

[C++]

HRESULT ProcessMessage(

BSTR Document,

BSTR* ResponseDocument

);

Parameters

Document

[in] Contains the document to be processed.

ResponseDocument

[retval, out] In C++, contains the response document processed by the component, if available. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns the response document, if available.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Components can return a response string to pass back a text-based response to an application, using the SubmitSync method of the IInterchange interface to send documents.

Components must raise an error if a problem with processing occurs so that the document can be retransmitted or sent to the Suspended queue. If no error is returned, the server assumes that the component successfully processed the data.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: btsaic.h
Library: Microsoft BizTalk Server Application Interface Components 1.0 Type Library (btscomplib.tlb)


IPipelineComponent

Creates custom pipeline components that can execute in Microsoft BizTalk Server 2002 to extend its functionality.

Hierarchy

IUnknown

|--IPipelineComponent

Declaration

[Visual Basic]

Class IPipelineComponent

[C++]

interface IPipelineComponent : IUnknown

Members

IPipelineComponent defines the following methods:

Method | Description
EnableDesign | Configures the component for execution in one of two modes: design mode or execution mode.
Execute | Executes the operation expected of the component, given the transport IDictionary object and other configuration settings.

Remarks

Application integration components must be properly registered so that BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Application integration components register themselves with the category ID CATID_BIZTALK_AIC. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)

Related Topics

Application Integration Components

Pipeline Components in Visual Basic

Pipeline Components in Visual C++


EnableDesign Method

Configures the component for execution in one of two modes: design mode or execution mode.

Member List

IPipelineComponent

|--EnableDesign

|--Execute

Method Declaration

[Visual Basic]

Sub EnableDesign( _

Enable As Boolean _

)

[C++]

HRESULT EnableDesign(

BOOL Enable

);

Parameters

Enable

[in] Indicates the mode of the component. True specifies that the component runs in design mode. False specifies execution mode. The default value is False.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The pipeline component runs in execution mode by default.

This method is called when the Override messaging port defaults page is opened in the Channel Wizard's Advanced Configuration page. It is also called when the property page is closed and the Enable parameter is set to true. Design mode is not enabled unless this method has been called with the Enable parameter set to True.

Design-only fields are returned only when the Enable parameter is set to true. Otherwise, the IDictionary object passed to the server contains unnecessary information.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)


Execute Method

Executes the operation expected of the component, given the transport IDictionary object and other configuration settings.

Member List

IPipelineComponent

|--EnableDesign

|--Execute

Method Declaration

[Visual Basic]

Function Execute( _

DispOrder As Object, _

DispContext As Object, _

Flags As Long _

) As Long

[C++]

HRESULT Execute(

IDispatch* DispOrder,

IDispatch* DispContext,

long Flags,

long* ErrorLevel

);

Parameters

DispOrder

[in] Transport IDictionary object.

DispContext

[in] Not supported for this release.

Flags

[in] Reserved.

ErrorLevel

[out, retval] Reserved.

Return Values

In Visual Basic, this method returns the error level.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Microsoft BizTalk Server 2002 calls this method, passing in the transport IDictionary object. The component can read these IDictionary object values, perform the necessary functions, and optionally write new values back to the transport IDictionary object for further processing.

For a component designed to run in BizTalk Server 2002, the first parameter is a Transport Dictionary object. The Transport Dictionary values can be read by the component for processing. The string values supplied by the server for all application integration components (AICs) are defined in the Handling Data Passed to AICs topic.

For a component that runs in a Commerce Server order-processing pipeline, the first parameter contains the OrderForm object.

This method is called at run time when the server is sending a document to the component. This method is called immediately after the SetConfigData method of the IPipelineComponentAdmin interface. The document is passed in the first parameter as a dictionary within the working_data field of the IDictionary object. Components can add the ResponseField key to the IDictionary object to pass back a text-based response to an application, using the SubmitSync method of the IInterchange interface.

The component must raise an error if a problem with processing occurs so that the server can retry transmission later and, after all retries, send the document to the Suspended queue. If no error is returned, the server assumes that the component successfully processed the data.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)


IPipelineComponentAdmin

Gets and sets configuration information for a component. Use IPipelineComponentAdmin between the component and the component user interface.

Hierarchy

IDispatch

|--IPipelineComponentAdmin

Declaration

[Visual Basic]

Class IPipelineComponentAdmin

[C++]

interface IPipelineComponentAdmin : IDispatch

Members

IPipelineComponentAdmin defines the following methods:

Method | Description
GetConfigData | Returns an IDictionary object that contains the configuration data for the component to be used to display these values.
SetConfigData | The SetConfigData method sets the configuration for a component, using the contents of an IDictionary object.

Remarks

Application integration components must be properly registered so that BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Application integration components register themselves with the category ID CATID_BIZTALK_AIC. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)

Related Topics

Application Integration Components

Pipeline Components in Visual Basic

Pipeline Components in Visual C++


GetConfigData Method

Returns an IDictionary object that contains the configuration data for the component to be used to display these values.

Member List

IPipelineComponentAdmin

|--GetConfigData

|--SetConfigData

Method Declaration

[Visual Basic]

Function GetConfigData() As Object

[C++]

HRESULT GetConfigData(

IDispatch** ConfigDictionary

);

Parameters

ConfigDictionary

[out, retval] In C++, an IDictionary object from which the user interface can read the configuration data. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method optionally returns a CDictionary object from which the user interface can read the configuration data.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

GetConfigData enables the user interface component to read the current value from the component and display it on the property page initially.

When an IBizTalkPort object is first saved, this method is called to get the defaults for use in autoconfiguring the application integration component (AIC) from the IDictionary object provided. Components must provide defaults for all mandatory properties, whenever possible.

This method is called when the user selects the property page. It is used to supply property page defaults. It is called again when the property page is closed. The contents of this returned IDictionary object are not used.

Components must always return a valid dictionary pointer from GetConfigData.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)


SetConfigData Method

The SetConfigData method sets the configuration for a component, using the contents of an IDictionary object.

Member List

IPipelineComponentAdmin

|--GetConfigData

|--SetConfigData

Method Declaration

[Visual Basic]

Sub SetConfigData( _

ConfigDictionary As Object _

)

[C++]

HRESULT SetConfigData(

IDispatch* ConfigDictionary

);

Parameters

ConfigDictionary

[in] Contains an IDictionary object that contains the configuration information.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

With this method, the user interface can set or change these values. SetConfigData enables the user interface to write the updated value from the property page to the component.

The server calls SetConfigData when the property page is saved. It is used to verify the values entered by the user on the property page. The contents of this provided IDictionary object are also stored in the database.

This method is called immediately before the Execute method of the IPipelineComponent interface at run time, when the server is ready to send a document to the component. Data stored during design time from autoconfiguration or from property-page updates is passed to the component to allow for property setup prior to calling Execute.

Components validate the properties provided in SetConfigData and raise an error if any of the properties are invalid or missing.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: pipecomp.h
Library: Microsoft Commerce 2000 Default Pipeline Components Type Library (pipecomplib.tlb)


ISchemaImporter

Handles the importing of DTDs, XDRs, and well-formed XML documents.

Hierarchy

IDispatch

|--ISchemaImporter

Declaration

[Visual Basic]

Class ISchemaImporter

[C++]

interface ISchemaImporter : IDispatch

Members

ISchemaImporter defines the following properties:

Property | Description
ImportFormatDescription | Contains descriptive text about a supported import format.
ImportFormatIcon | Contains an icon for a supported import format.
NumberOfSupportedImportFormats | Contains the number of supported data formats from which a schema can be extracted.

ISchemaImporter defines the following method:

Method | Description
ExtractXMLSchema | Extracts a schema from a document.

Remarks

Custom XML import components must be properly registered so that Microsoft BizTalk Server 2002 can recognize that they belong to BizTalk Server 2002. Custom XML import components register themselves with the category ID CATID_BIZTALK_IDocSpecExtension. The CATIDs are defined in the bts_sdk_guids.h file. For more information, see Registering Custom Components.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


ExtractXMLSchema Method

Extracts a schema from a document.

Member List

ISchemaImporter

|--ExtractXMLSchema

|--ImportFormatDescription

|--ImportFormatIcon

|--NumberOfSupportedImportFormats

Method Declaration

[Visual Basic]

Function ExtractXMLSchema( _

FormatIndex As Long, _

DocumentPath As String _

) As Object

[C++]

HRESULT ExtractXMLSchema(

long FormatIndex ,

BSTR DocumentPath ,

IDispatch** SchemaDOM

);

Parameters

FormatIndex

[in] Contains an index value that specifies the type of document from which to import the schema. Use the value 0 to import well-formed XML, 1 to import a document type definition (DTD), or 2 to import an XDR schema.

DocumentPath

[in] Contains the path to the document from which to import the schema.

SchemaDOM

[out, retval] In C++, contains an IDispatch interface that contains the extracted XML schema. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this method returns an Object that contains information about the extracted XML schema.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


ImportFormatDescription Property

Contains descriptive text about a supported import format.

Member List

ISchemaImporter

|--ExtractXMLSchema

|--ImportFormatDescription

|--ImportFormatIcon

|--NumberOfSupportedImportFormats

Property Declaration

[Visual Basic]

Property ImportFormatDescription( _

FormatIndex As Long _

) As String

[C++]

HRESULT get_ImportFormatDescription(

long FormatIndex ,

BSTR* Description

);

Parameters

FormatIndex

[in] Contains an index value that specifies the type of document from which to import the schema. Use the value 0 to import well-formed XML, 1 to import a document type definition (DTD), or 2 to import an XDR schema.

Description

[out, retval] In C++, contains a textual description of the input document format. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a textual description of the input document format.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


ImportFormatIcon Property

Contains an icon for a supported import format.

Member List

ISchemaImporter

|--ExtractXMLSchema

|--ImportFormatDescription

|--ImportFormatIcon

|--NumberOfSupportedImportFormats

Property Declaration

[Visual Basic]

Property ImportFormatIcon( _

FormatIndex As Long _

) As Long

[C++]

HRESULT get_ImportFormatIcon(

long FormatIndex,

long* IconID

);

Parameters

FormatIndex

[in] Contains an index value that specifies the type of document from which to import the schema. Use the value 0 to import well-formed XML, 1 to import a document type definition (DTD), or 2 to import an XDR schema.

IconID

[out, retval] In C++, contains the icon identifier for the input format. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the icon identifier for the input format.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read only-property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


NumberOfSupportedImportFormats Property

Contains the number of supported data formats from which a schema can be extracted.

Member List

ISchemaImporter

|--ExtractXMLSchema

|--ImportFormatDescription

|--ImportFormatIcon

|--NumberOfSupportedImportFormats

Property Declaration

[Visual Basic]

Property NumberOfSupportedImportFormats As Long

[C++]

HRESULT get_NumberOfSupportedImportFormats(

long* Number

);

Parameters

Number

[out, retval] In C++, indicates the number of supported import formats. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of supported import formats.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


ISchemaImporterError

Identifies and deciphers errors or warnings.

Hierarchy

IDispatch

|--ISchemaImporterError

Declaration

[Visual Basic]

Class ISchemaImporterError

[C++]

interface ISchemaImporterError : IDispatch

Members

ISchemaImporterError defines the following properties:

Property | Description
IsWarning | Contains a value that identifies the object as an error or a warning.
NodePath | Contains the path to the node that generated the error or warning.
Text | Contains the error or warning message.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


IsWarning Property

Contains a value that identifies the object as an error or a warning.

Member List

ISchemaImporterError

|--IsWarning

|--NodePath

|--Text

Property Declaration

[Visual Basic]

Property IsWarning As Boolean

[C++]

HRESULT get_IsWarning(

VARIANT_BOOL* IsWarning

);

Parameters

IsWarning

[out, retval] In C++, contains a value that indicates whether or not the object is a warning. VARIANT_TRUE indicates that this is a warning object; VARIANT_FALSE indicates that this is an error object. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the object is a warning. True indicates that this is a warning object; False indicates that this is an error object.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


NodePath Property

Contains the path to the node that generated the error or warning.

Member List

ISchemaImporterError

|--IsWarning

|--NodePath

|--Text

Property Declaration

[Visual Basic]

Property NodePath As String

[C++]

HRESULT get_NodePath(

BSTR* NodePath

);

Parameters

NodePath

[out, retval] In C++, contains the fully qualified name of the node that generated the error or warning. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the fully qualified name of the node that generated the error or warning.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


Text Property

Contains the error or warning message.

Member List

ISchemaImporterError

|--IsWarning

|--NodePath

|--Text

Property Declaration

[Visual Basic]

Property Text As String

[C++]

HRESULT get_Text(

BSTR* errText

);

Parameters

errText

[out, retval] In C++, contains the text associated with the error or warning. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the text associated with the error or warning.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


ISchemaImporterErrorProvider

Returns errors or warnings.

Hierarchy

IDispatch

|--ISchemaImporterErrorProvider

Declaration

[Visual Basic]

Class ISchemaErrorProvider

[C++]

interface ISchemaErrorProvider : IDispatch

Members

ISchemaImporterErrorProvider defines the following properties:

Property | Description
Error | Contains the error or warning.
NumberOfErrors | Contains the number of errors or warnings.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


Error Property

Contains the error or warning.

Member List

ISchemaImporterErrorProvider

|--Error

|--NumberOfErrors

Property Declaration

[Visual Basic]

Property Error( _

Index As Long _

) As ISchemaImporterError

[C++]

HRESULT get_Error(

long Index,

IschemaImporterError** Error

);

Parameters

Index

[in] Contains the index of the error or warning.

Error

[out, retval] In C++, contains an ISchemaImporterError interface that contains the error or warning. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a SchemaImporterError object that contains the error or warning.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


NumberOfErrors Property

Contains the number of errors or warnings.

Member List

ISchemaImporterErrorProvider

|--Error

|--NumberOfErrors

Property Declaration

[Visual Basic]

Property NumberOfErrors As Long

[C++]

HRESULT get_NumberOfErrors(

long* NumberOfErrors

);

Parameters

NumberOfErrors

[out, retval] In C++, indicates the number of errors. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of errors.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SchemaImporter.h
Library: Microsoft BizTalk Server Import Extension Module 1.0 Type Library (ExtensionMod.dll)


Enumerations

The following enumerations provide possible property and parameter values:

  • CONNECTION_TYPE

  • DTA_ACK_STATUS

  • FUNC_CATEGORY

  • FUNC_TYPE

  • GeneratedReceiptLevel

  • SCRIPT_CATEGORY


CONNECTION_TYPE

Specifies the connection type.

[Visual Basic]

Enum CONNECTION_TYPE

[C++]

enum CONNECTION_TYPE

Members

CONNECT_TYPE_NONE

[0] The connection type is none.

CONNECT_TYPE_FIELD

[1] The connection type is field.

CONNECT_TYPE_RECORD

[2] The connection type is record.

CONNECT_TYPE_RECORD_CONTENT

[4] The connection type is record content.

CONNECT_TYPE_FUNC_STRING

[8] The connection type function is string.

CONNECT_TYPE_FUNC_MATH

[16] The connection type function is mathematical.

CONNECT_TYPE_FUNC_DATACONV

[32] The connection type function is data conversion.

CONNECT_TYPE_FUNC_DATETIME_FMT

[64] The connection type function is date/time format.

CONNECT_TYPE_FUNC_SCIENTIFIC

[128] The connection type function is scientific.

CONNECT_TYPE_FUNC_BOOLEAN

[256] The connection type function is Boolean.

CONNECT_TYPE_FUNC_SCRIPTER

[1024] The connection type function is script.

CONNECT_TYPE_FUNC_COUNT

[2048] The connection type function is count.

CONNECT_TYPE_FUNC_INDEX

[2048] The connection type function is index.

CONNECT_TYPE_FUNC_CUMULATIVE

[4096] The connection type function is cumulative.

CONNECT_TYPE_FUNC_VALUE_MAPPING

[8192] The connection type function is value mapping.

CONNECT_TYPE_FUNC_LOOPING

[16384] The connection type function is looping.

CONNECT_TYPE_FUNC_ITERATION

[32768] The connection type function is iteration.

CONNECT_TYPE_FUNC_DBLOOKUP

[65536] The connection type function is database lookup.

CONNECT_TYPE_FUNC_DBEXTRACT

[131072] The connection type function is database extraction.

CONNECT_TYPE_ALL

[-1] The connection type includes all connection types.

CONNECT_TYPE_ALL_EXCEPT_RECORD

[-3] The connection type includes all connection types except records.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)

Related Topics

GetFunctionParameter


DTA_ACK_STATUS

Indicates the acknowledgement status.

[Visual Basic]

Enum DTA_ACK_STATUS

[C++]

enum DTA_ACK_STATUS

Members

DTA_ACK_NONE

[0] No receipt is expected.

DTA_ACK_PENDING

[1] The receipt is expected but has not yet arrived.

DTA_ACK_OVERDUE

[2] The receipt has timed out.

DTA_ACK_ACCEPTED

[3] The receipt has arrived with a status of accepted.

DTA_ACK_PARTIALLY_ACCEPTED

[4] The receipt has arrived with a status of accepted with errors.

DTA_ACK_REJECTED

[5] The receipt has arrived with a status of rejected.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSDocTracking.h
Library: Microsoft BizTalk Server Doc Tracking 1.0 Type Library (CISDTA.dll)

Related Topics

AckDocument

AckGroup

AckInterchange


FUNC_CATEGORY

Defines the values to specify the functoid palette on which the custom functoid will appear.

[Visual Basic]

Enum FUNC_CATEGORY

[C++]

enum FUNC_CATEGORY

Members

FUNC_CATEGORY_STRING

[3] The function category is string.

FUNC_CATEGORY_MATH

[4] The function category is mathematical.

FUNC_CATEGORY_DATACONV

[5] The function category is data conversion.

FUNC_CATEGORY_DATETIME_FMT

[6] The function category is date/time format.

FUNC_CATEGORY_SCIENTIFIC

[7] The function category is scientific.

FUNC_CATEGORY_BOOLEAN

[8] The function category is Boolean.

FUNC_CATEGORY_SCRIPTER

[9] The function category is script.

FUNC_CATEGORY_COUNT

[10] The function category is count. This value is not supported for this release.

FUNC_CATEGORY_INDEX

[11] The function category is index.

FUNC_CATEGORY_CUMULATIVE

[12] The function category is cumulative.

FUNC_CATEGORY_VALUE_MAPPING

[13] The function category is value mapping. This value is not supported for this release.

FUNC_CATEGORY_LOOPING

[14] The function category is looping. This value is not supported for this release.

FUNC_CATEGORY_ITERATION

[15] The function category is iteration. This value is not supported for this release.

FUNC_CATEGORY_DBLOOKUP

[16] The function category is database lookup. It is not recommended to add custom functoids to the Database tab on the functoid palette. See the note following this table for information on adding functoids to the Advanced tab.

FUNC_CATEGORY_DBEXTRACT

[17] The function category is database extraction. It is not recommended to add custom functoids to the Database tab on the functoid palette. See the note following this table for information on adding functoids to the Advanced tab.

FUNC_CATEGORY_UNKNOWN

[31] The function category is unknown.

Remarks

Custom functoids using a category value between 18 and 31 appear on the Advanced tab in the functoid palette.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)

Related Topics

GetFunctionDescripter


FUNC_TYPE

Specifies the function type.

[Visual Basic]

Enum FUNC_TYPE

[C++]

enum FUNC_TYPE

Members

FUNC_TYPE_STD

[1] The function type is standard.

FUNC_TYPE_VARIABLEINPUT

[2] The function type is variable input.

FUNC_TYPE_SCRIPTOR

[3] The function type is script.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)

Related Topics

GetFunctionDescripter


GeneratedReceiptLevel

Specifies the generated receipt level.

This enumeration is only supported in C++.

enum GeneratedReceiptLevel

Members

NoReceiptGenerated

[0] No receipt is created.

DocReceiptGenerated

[1] A receipt is generated for each document.

GroupReceiptGenerated

[2] A receipt is generated for each group.

InterchangeReceiptGenerated

[3] A receipt is generated for each interchange.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: BTSParserComps.h

Related Topics

GetNextDocument


SCRIPT_CATEGORY

Specifies the script category.

[Visual Basic]

Enum SCRIPT_CATEGORY

[C++]

enum SCRIPT_CATEGORY

Members

SCRIPT_CATEGORY_VBSCRIPT

[0] The custom functoid function is written in the Microsoft Visual Basic Scripting Edition (VBScript) language.

SCRIPT_CATEGORY_JSCRIPT

[1] The custom functoid function is written in the Microsoft JScript language.

SCRIPT_CATEGORY_XSLSCRIPT

[2] The custom functoid function is written in the Extensible Stylesheet Language (XSL). This value is not supported for this release.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: Functoid.h
Library: Microsoft BizTalk Server Canned Functoids 1.0 Type Library (CannedFunctoid.dll)

Related Topics

GetFunctionDescripter


Orchestration Services Reference

This section provides reference information about application programming interfaces (APIs) used by Microsoft BizTalk Server 2002 for both C++ and Microsoft Visual Basic programming.

Reference information is provided for all interfaces, methods, and properties exposed for accessing orchestration services:

  • Interfaces

In addition, a complete list of Error Messages is provided.


Interfaces

The following COM interfaces are documented:

  • IWFGroupAdmin

  • IWFProxy

  • IWFSystemAdmin

  • IWFWorkflowInstance


IWFGroupAdmin

Allows a client application to control running instances of an XLANG schedule. Use IWFGroupAdmin to stop, suspend, resume, and retrieve information about all the schedule instances associated with a group manager.

Hierarchy

IDispatch

|--IWFGroupAdmin

Declaration

[Visual Basic]

Class IWFGroupAdmin

[C++]

interface IWFGroupAdmin : IDispatch

Members

IWFGroupAdmin defines the following properties:

Property | Description
Count | Contains the number of running XLANG schedule instances associated with this group manager.
FullyQualifiedName | Contains the moniker of this group manager.
InstanceIsResident | Contains a value that indicates whether the specified XLANG schedule instance is currently resident in memory.
InstanceIsSuspended | Contains a value that indicates whether the specified XLANG schedule instance is currently in a suspended state.
Name | Contains the name of this group manager.
UseFileDSN | Contains a value that indicates whether a Data Source Name (DSN) file is used for dehydrating the XLANG schedule instances.

IWFGroupAdmin defines the following methods:

Method | Description
ResumeInstance | Resumes the execution of an XLANG schedule instance in a suspended state.
Shutdown | Stops the group manager and dehydrates all running XLANG schedule instances.
Startup | Starts all the dehydrated XLANG schedule instances for the current group manager.
SuspendInstance | Pauses the running XLANG schedule instance in its current state.
TerminateInstance | Stops execution of the running XLANG schedule instance.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)

Related Topics

Accessing Group Managers

XLANG Interfaces


Count Property

Contains the number of running XLANG schedule instances associated with this group manager.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property Count As Long

[C++]

HRESULT get_Count(

long* Count

);

Parameters

Count

[out, retval] In C++, contains the number of running schedule instances associated with this group manager. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of running schedule instances associated with this group manager.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


FullyQualifiedName Property

Contains the moniker of this group manager.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property FullyQualifiedName As String

[C++]

HRESULT get_FullyQualifiedName(

BSTR* FullyQualifiedName

);

Parameters

FullyQualifiedName

[out, retval] In C++, contains the moniker of this group manager. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the moniker of this group manager.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Although a group manager can be instantiated through a local moniker, this property always includes the full Domain Name Services (DNS) style system name. For example, suppose the default XLANG Scheduler Group Manager, named XLANG Scheduler, is running on a computer named MyMachine in the domain vigorair-18.com. The FullyQualifiedName property would contain a value of sked://MyMachine.vigorair-18.com!XLANG Scheduler.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)

Related Topics

Moniker Syntax


InstanceIsResident Property

Contains a value that indicates whether the specified XLANG schedule instance is currently resident in memory.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property InstanceIsResident( _

InstanceId As String _

) As Boolean

[C++]

HRESULT get_InstanceIsResident(

BSTR InstanceId,

VARIANT_BOOL* IsResident

);

Parameters

InstanceId

[in] Contains the globally unique identifier (GUID) assigned to the schedule instance.

IsResident

[out, retval] In C++, contains a value that indicates whether or not the specified schedule instance is currently resident in memory. VARIANT_TRUE indicates that the specified schedule instance is currently resident in memory; VARIANT_FALSE indicates that the specified schedule instance is not currently resident in memory. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the specified schedule instance is currently resident in memory. True indicates that the specified schedule instance is currently resident in memory; False indicates that the specified schedule instance is not currently resident in memory.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


InstanceIsSuspended Property

Contains a value that indicates whether the specified XLANG schedule instance is currently in a suspended state.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property InstanceIsSuspended( _

InstanceId As String _

) As Boolean

[C++]

HRESULT get_InstanceIsSuspended(

BSTR InstanceId,

VARIANT_BOOL* IsSuspended

);

Parameters

InstanceId

[in] Contains the globally unique identifier (GUID) assigned to the schedule instance.

IsSuspended

[out, retval] In C++, contains a value that indicates whether or not the specified schedule instance is currently in a suspended state. VARIANT_TRUE indicates that the specified schedule instance is currently in a suspended state; VARIANT_FALSE indicates that the specified schedule instance is not currently in a suspended state. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the specified schedule instance is currently in a suspended state. VARIANT_TRUE indicates that the specified schedule instance is currently in a suspended state; VARIANT_FALSE indicates that the specified schedule instance is not currently in a suspended state.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

This property should be checked prior to calling the ResumeInstance method.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


Name Property

Contains the name of this group manager.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property Name As String

[C++]

HRESULT get_Name(

BSTR* Name

);

[
Parameters

Name

[out, retval] In C++, contains the name of this group manager. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of this group manager.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

This property is the same as the name of the hosting COM+ application.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


ResumeInstance Method

Resumes the execution of an XLANG schedule instance in a suspended state.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub ResumeInstance( _

InstanceId As String _

)

[C++]

HRESULT ResumeInstance(

BSTR InstanceId

);

Parameters

InstanceId

[in] Contains the globally unique identifier (GUID) assigned to the schedule instance to be resumed.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The schedule instance can be paused with the SuspendInstance method. Prior to calling the ResumeInstance method, the InstanceIsSuspended property should be checked.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


Shutdown Method

Stops the group manager and dehydrates all running XLANG schedule instances.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub Shutdown( )

[C++]

HRESULT Shutdown( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

Prior to stopping the group manager, all running schedule instances associated with this group manager are dehydrated to the database specified in the Data Source Name (DSN) file, and requests for activation of any new schedule instances are refused until shutdown is completed.

Any component that is bound in an XLANG schedule should not invoke this method to stop the group manager, as this can produce unexpected results.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


Startup Method

Starts all the dehydrated XLANG schedule instances for the current group manager.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub Startup( )

[C++]

HRESULT Startup( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The XLANG Scheduler System Manager normally calls this method. Users should not call this method directly.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


SuspendInstance Method

Pauses the running XLANG schedule instance in its current state.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub SuspendInstance( _

InstanceId As String _

)

[C++]

HRESULT SuspendInstance(

BSTR InstanceId

);

Parameters

InstanceId

[in] Contains the globally unique identifier (GUID) assigned to the schedule instance to be suspended.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

The schedule instance can be restarted with the ResumeInstance method.

This method might block if actions with COM-bound ports are waiting for a method to complete, or if a short-lived transaction is currently in progress.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


TerminateInstance Method

Stops execution of the running XLANG schedule instance.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub TerminateInstance( _

InstanceId As String _

)

[C++]

HRESULT TerminateInstance(

BSTR InstanceId

);

Parameters

InstanceId

[in] Contains the globally unique identifier (GUID) assigned to the schedule instance to be stopped.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

A terminated schedule instance can never be restarted or resumed.

This method might block if actions with COM-bound ports are waiting for a method to complete, or if a short-lived transaction is currently in progress.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


UseFileDSN Property

Contains a value that indicates whether a Data Source Name (DSN) file is used for dehydrating the XLANG schedule instances.

Member List

IWFGroupAdmin

|--Count

|--FullyQualifiedName

|--InstanceIsResident

|--InstanceIsSuspended

|--Name

|--ResumeInstance

|--Shutdown

|--Startup

|--SuspendInstance

|--TerminateInstance

|--UseFileDSN

Property Declaration

[Visual Basic]

Property UseFileDSN As Boolean

[C++]

HRESULT get_UseFileDSN(

VARIANT_BOOL* UseFileDSN

);

Parameters

UseFileDSN

[out, retval] In C++, contains a value that indicates whether or not the group manager uses a DSN file for dehydrating schedule instances. VARIANT_TRUE indicates that the group manager uses a DSN file for dehydrating schedule instances; VARIANT_FALSE indicates that the group manager does not use a DSN file for dehydrating schedule instances. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the group manager uses a DSN file for dehydrating schedule instances. True indicates that the group manager uses a DSN file for dehydrating schedule instances; False indicates that the group manager does not use a DSN file for dehydrating schedule instances.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

The value of this property is set when the group manager process is launched. The DSN setting in the COM+ catalog is changed either on the XLANG tab of the XLANG Scheduler Properties dialog box or by setting the UseFileDSN property on the IWFSystemAdmin interface. If the DSN value is changed while the group manager is running, the value of this property is not dynamically updated. The new value is not reflected until the next time the group manager is launched. Updates to this property require the caller to be in the XLANG Administrator role and are not normally performed by user code.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


IWFProxy

Contains information about ports in an XLANG schedule instance that are bound to a COM component.

Hierarchy

IDispatch

|--IWFProxy

Declaration

[Visual Basic]

Class IWFProxy

[C++]

interface IWFProxy : IDispatch

Members

IWFProxy defines the following properties:

Property | Description
FullyQualifiedName | Contains the fully qualified name of a COM-bound port.
WorkflowInstance | Contains a reference to the current XLANG schedule instance.

Remarks

Use IWFProxy to obtain a schedule instance.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)

Related Topics

Activating an XLANG Schedule Instance


FullyQualifiedName Property

Contains the fully qualified name of a COM-bound port.

Member List

IWFProxy

|--FullyQualifiedName

|--WorkflowInstance

Property Declaration

[Visual Basic]

Property FullyQualifiedName As String

[C++]

HRESULT get_FullyQualifiedName(

BSTR* FullyQualifiedName

);

Parameters

FullyQualifiedName

[out, retval] Contains the moniker of the port. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the moniker of the port.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

The moniker retrieved with this property can be used with the COM GetObject function to obtain a reference to the XLANG schedule instance. This moniker is valid as long as the schedule instance is running. If the schedule instance is dehydrated and rehydrated for any reason, such as rebooting the system, the moniker remains valid. Once the schedule instance completes, or ends by using the TerminateInstance method, the moniker can no longer be used.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


WorkflowInstance Property

Contains a reference to the current XLANG schedule instance.

Member List

IWFProxy

|--FullyQualifiedName

|--WorkflowInstance

Property Declaration

[Visual Basic]

Property WorkflowInstance As IWFWorkflowInstance

[C++]

HRESULT get_WorkflowInstance(

IWFWorkflowInstance** ScheduleInstance

);

Parameters

ScheduleInstance

[out, retval] Contains an IWFWorkflowInstance object that contains the current schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns an IWFWorkflowInstance object that contains the current schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


IWFSystemAdmin

Provides a client application with system-wide administrative control over the XLANG Scheduler Engine.

Hierarchy

IDispatch

|--IWFSystemAdmin

Declaration

[Visual Basic]

Class SysMgr

[C++]

interface IWFSystemAdmin : IDispatch

Members

IWFSystemAdmin defines the following properties:

Property | Description
Count | Contains the number of group managers associated with this XLANG Scheduler System Manager.
FullyQualifiedName | Contains the fully qualified DNS-style name of the XLANG Scheduler System Manager.
IsWorkflowHost | Contains a value that indicates whether the COM+ server application is an XLANG Scheduler Engine host.
Item | Contains a reference to the named schedule group.
UseFileDSN | Contains a value that indicates whether a COM+ server application uses a Data Source Name (DSN) file for dehydrating the XLANG schedule instances.

IWFSystemAdmin defines the following methods:

Method | Description
ShutdownAll | Stops the group managers and terminates their associated COM+ applications.
ShutdownApp | Stops a specific group manager application and terminates the associated COM+ application.
Startup | Starts all group managers.
TestAdminStatus | Determines whether a caller on IWFGroupAdmin is an XLANG Scheduler Engine administrator.

Remarks

Use IWFSystemAdmin to start, stop, and retrieve information about the group managers.

All XLANG Scheduler System Manager objects must have an associated Data Source Name (DSN) to support the dehydration and rehydration of long-running business processes. Therefore, you must create a DSN for the XLANG Scheduler System Manager by using the ODBC Data Source Administrator. XLANG schedules run by an XLANG Scheduler System Manager without a DSN configured will generate an error. For more information about creating a DSN, see Change the DSN settings for a COM+ application.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)

Related Topics

Accessing the XLANG Scheduler System Manager

XLANG Interfaces


Count Property

Contains the number of group managers associated with this XLANG Scheduler System Manager.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Property Declaration

[Visual Basic]

Property Count As Long

[C++]

HRESULT get_Count(

long* Count

);

Parameters

Count

[out, retval] Contains the number of running group managers. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the number of running group managers.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


FullyQualifiedName Property

Contains the fully qualified DNS-style name of the XLANG Scheduler System Manager.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Property Declaration

[Visual Basic]

Property FullyQualifiedName As String

[C++]

HRESULT get_FullyQualifiedName(

BSTR* FullyQualifiedName

);

Parameters

FullyQualifiedName

[out, retval] Contains the moniker of this XLANG Scheduler System Manager. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the moniker of this XLANG Scheduler System Manager.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Although an XLANG Scheduler System Manager can be instantiated through a local moniker, this property always includes the full Domain Name Services (DNS) style system name. For example, suppose the XLANG Scheduler System Manager is running on a computer named MyMachine in the domain vigorair-18.com. The FullyQualifiedName property would contain a value of sked://MyMachine.vigorair-18.com.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)

Related Topics

Moniker Syntax


IsWorkflowHost Property

Contains a value that indicates whether the COM+ server application is an XLANG Scheduler Engine host.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Property Declaration

[Visual Basic]

Property IsWorkflowHost( _

AppName As String _

) As Boolean

[C++]

HRESULT get_IsWorkflowHost(

BSTR AppName,

VARIANT_BOOL* IsWorkflowHost

);

HRESULT put_IsWorkflowHost(

BSTR AppName,

VARIANT_BOOL IsWorkflowHost

);

Parameters

AppName

[in] Contains the COM+ server application name.

IsWorkflowHost

[out, retval], [in] In C++, contains a value that indicates whether or not the COM+ server application is hosting the XLANG Scheduler Engine. VARIANT_TRUE indicates that the COM+ server application is hosting the XLANG Scheduler Engine; VARIANT_FALSE indicates that the COM+ server application is not hosting the XLANG Scheduler Engine. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the COM+ server application is hosting the XLANG Scheduler Engine. True indicates that the COM+ server application is hosting the XLANG Scheduler Engine; False indicates that the COM+ server application is not hosting the XLANG Scheduler Engine.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This property cannot be set on the XLANG Scheduler Engine application, or on any COM+ application marked as read-only.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


Item Property

Contains a reference to the named schedule group.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Property Declaration

[Visual Basic]

Property Item( _

GrpMgrName As String _

) As Unknown

[C++]

HRESULT get_Item(

BSTR GrpMgrName,

IUnknown** Item

);

Parameters

GrpMgrName

[in] Contains the group name corresponding to the hosting COM+ server application name. Group names are case sensitive and can contain spaces.

Item

[out, retval] Contains an object that refers to a group manager. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns an object that refers to a group manager.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


ShutdownAll Method

Stops the group managers and terminates their associated COM+ applications.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub ShutdownAll( )

[C++]

HRESULT ShutdownAll( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

When the ShutdownAll method is called, new schedule activations are disabled and the shutdown notice is propagated to all running group managers. Once this method has completed, all group managers are stopped and the system can be safely rebooted.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


ShutdownApp Method

Stops a specific group manager application and terminates the associated COM+ application.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub ShutdownApp( _

AppName As String _

)

[C++]

HRESULT ShutdownApp(

BSTR AppName

);

Parameters

AppName

[in] Contains the COM+ server application name to be stopped.

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

When the ShutdownApp method is called, new schedule activations on the named application are disabled and all running XLANG schedule instances associated with that application are stopped. If this method is called on the default XLANG Scheduler Group Manager, all group managers are shut down. Calling this method on the default XLANG Scheduler Group Manager is equivalent to calling the ShutdownAll method.

Note

  • The COM+ application name of the default XLANG Scheduler Group Manager is XLANG Scheduler.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


StartUp Method

Starts all group managers.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub StartUp( )

[C++]

HRESULT StartUp( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

When this method is invoked, rehydration is initiated for all group managers and, subsequently, all XLANG schedules. This method is asynchronous, and it can complete before all group managers and schedules are running.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


TestAdminStatus Method

Determines whether a caller on IWFSystemAdmin is an XLANG Scheduler Engine administrator.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Method Declaration

[Visual Basic]

Sub TestAdminStatus( )

[C++]

HRESULT TestAdminStatus( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This method is intended for internal use by the group managers.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


UseFileDSN Property

Contains a value that indicates whether a COM+ server application uses a Data Source Name (DSN) file for dehydrating the XLANG schedule instances.

Member List

IWFSystemAdmin

|--Count

|--FullyQualifiedName

|--IsWorkflowHost

|--Item

|--ShutdownAll

|--ShutdownApp

|--Startup

|--TestAdminStatus

|--UseFileDSN

Property Declaration

[Visual Basic]

Property UseFileDSN( _

AppName As String _

) As Boolean

[C++]

HRESULT get_UseFileDSN(

BSTR AppName,

VARIANT_BOOL* UseFileDSN

);

HRESULT put_UseFileDSN(

BSTR AppName,

VARIANT_BOOL* UseFileDSN

);

Parameters

AppName

[in] Contains the COM+ server application name.

UseFileDSN

[out, retval], [in] In C++, contains a value that indicates whether or not the COM+ server application uses a DSN file for dehydrating schedule instances. VARIANT_TRUE indicates that the COM+ server application uses a DSN file for dehydrating schedule instances; VARIANT_FALSE indicates that the COM+ server application does not use a DSN file for dehydrating schedule instances. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the COM+ server application uses a DSN file for dehydrating schedule instances. True indicates that the COM+ server application uses a DSN file for dehydrating schedule instances; False indicates that the COM+ server application does not use a DSN file for dehydrating schedule instances.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

If this property is changed while any group manager is running, the value of this property is not dynamically updated in the group managers. Therefore, the UseFileDSN property value exposed by IWFGroupAdmin contains an incorrect value. The updated value is not reflected until the next time the group manager is launched.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SysMgr.h
Library: XLANG Scheduler - System Manager (SKEDSMGR.dll)


IWFWorkflowInstance

Allows a client application to navigate the ports of an XLANG schedule instance, check the completion status, and determine whether the schedule instance completed successfully.

Hierarchy

IDispatch

|--IWFWorkflowInstance

Declaration

[Visual Basic]

Class IWFWorkflowInstance

[C++]

interface IWFWorkflowInstance : IDispatch

Members

IWFWorkflowInstance defines the following properties:

Property | Description
CompletionStatus | Contains a value that indicates the success or failure of the XLANG schedule instance.
FullPortName | Contains the full name of a port in a form usable by the associated technology.
FullyQualifiedName | Contains the fully qualified name of this XLANG schedule instance.
InstanceId | Contains the globally unique identifier (GUID) assigned to the current XLANG schedule instance.
IsCompleted | Contains a value that indicates whether the XLANG schedule instance has finished executing.
ModuleId | Contains the globally unique identifier (GUID) of the XML module associated with the current XLANG schedule instance.
ModuleName | Contains the name of the XML module associated with the current XLANG schedule instance.
ParentInstanceID | Contains the globally unique identifier (GUID) assigned to the parent XLANG schedule instance of the current schedule instance.
Port | Contains a reference to the named port. This is applicable only to COM-based port bindings.

IWFWorkflowInstance defines the following method:

Method | Description
WaitForCompletion | Waits until the current XLANG schedule instance completes executing.

Remarks

Use IWFWorkflowInstance to gather information about a specific, running schedule instance.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)

Related Topics

Accessing a Running XLANG Schedule Instance

XLANG Interfaces


CompletionStatus Property

Contains a value that indicates the success or failure of the XLANG schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property CompletionStatus As Long

[C++]

HRESULT get_CompletionStatus(

long* CompletionStatus

);

Parameters

CompletionStatus

[out, retval] Contains the completion status of the schedule instance. A value of 0 indicates success. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the completion status of the schedule instance. A value of 0 indicates success.

In C++, this property returns an HRESULT value, indicating success or failure.

Note

  • A return value of S_OK does not indicate that the processes or applications associated with the schedule instance completed successfully. It indicates only that the schedule instance was completely processed by the XLANG Scheduler Engine, without errors.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


FullPortName Property

Contains the full name of a port in a form usable by the associated technology.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property FullPortName( _

Port As String _

) As String

[C++]

HRESULT get_FullPortName(

BSTR Port,

BSTR* FullPortName

);

Parameters

Port

[in] Contains the name of the port to be retrieved.

FullPortName

[out, retval] Contains the full port name. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the full port name.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

The full port name is returned in a form that is usable by the associated binding technology. For example, a port that is bound to a COM component returns a fully qualified moniker as the name of the port. For a port that is bound to Microsoft Message Queuing, this method returns the full path of the queue.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


FullyQualifiedName Property

Contains the fully qualified name of this XLANG schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property FullyQualifiedName As String

[C++]

HRESULT get_FullyQualifiedName(

BSTR* FullyQualifiedName

);

Parameters

FullyQualifiedName

[out, retval] Contains the moniker of the schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the moniker of the schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


InstanceId Property

Contains the globally unique identifier (GUID) assigned to the current XLANG schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property InstanceId As String

[C++]

HRESULT get_InstanceId(

BSTR* InstanceId

);

Parameters

InstanceId

[out, retval] Contains the GUID of the schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the GUID of the schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


IsCompleted Property

Contains a value that indicates whether the XLANG schedule instance has finished executing.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property IsCompleted As Boolean

[C++]

HRESULT get_IsCompleted(

VARIANT_BOOL* IsCompleted

);

Parameters

IsCompleted

[out, retval], In C++, contains a value that indicates whether or not the schedule instance has finished executing. VARIANT_TRUE indicates that the schedule instance has finished executing; VARIANT_FALSE indicates the schedule instance has not finished executing. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a value that indicates whether or not the schedule instance has finished executing. True indicates that the schedule instance has finished executing; False indicates the schedule instance has not finished executing.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


ModuleId Property

Contains the globally unique identifier (GUID) of the XML module associated with the current XLANG schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property ModuleId As String

[C++]

HRESULT get_ModuleId(

BSTR* ModuleId

);

Parameters

ModuleId

[out, retval] Contains the GUID of the XLANG module associated with the current schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the GUID of the XLANG module associated with the current schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


ModuleName Property

Contains the name of the XML module associated with the current XLANG schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property ModuleName As String

[C++]

HRESULT get_ModuleName(

BSTR* ModuleName

);

Parameters

ModuleName

[out, retval] Contains the name of the XLANG module associated with the current schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the name of the XLANG module associated with the current schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

The module name is defined in the XLANG schedule (.skx) file.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


ParentInstanceID Property

Contains the globally unique identifier (GUID) assigned to the parent XLANG schedule instance of the current schedule instance.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property ParentInstanceID As String

[C++]

HRESULT get_ParentInstanceID(

BSTR* ParentInstanceID

);

Parameters

ParentInstanceID

[out, retval] Contains the GUID of the parent schedule instance of the current schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns the GUID of the parent schedule instance of the current schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

In C++, the property returns a NULL value if no parent schedule instance exists.

In Visual Basic, the property returns a Nothing value if no parent schedule instance exists.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


Port Property

Contains a reference to the named port. This is applicable only to COM-based port bindings.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Property Declaration

[Visual Basic]

Property Port( _

Port As String _

) As Unknown

[C++]

HRESULT get_Port(

BSTR Port,

IUnknown** PortReference

);

Parameters

Port

[in] Contains the name of the port to which to obtain a reference.

PortReference

[out, retval] Contains a reference to a port in the current XLANG schedule instance. This parameter is not supported in Visual Basic. For more information, see "Return Values."

Return Values

In Visual Basic, this property returns a reference to a port in the current XLANG schedule instance.

In C++, this property returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Remarks

This is a read-only property.

The MK_E_NOOBJECT error code is returned if the moniker or port name passed in the Port parameter is incorrect.

In Visual Basic, the variable used for the port reference returned by using this property should be declared as a specific class or as a Variant. You can't obtain the port reference if you declare the variable as an Object since the port actually returns an IUnknown reference.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


WaitForCompletion Method

Waits until the current XLANG schedule instance completes executing.

Member List

IWFWorkflowInstance

|--CompletionStatus

|--FullPortName

|--FullyQualifiedName

|--InstanceId

|--IsCompleted

|--ModuleId

|--ModuleName

|--ParentInstanceID

|--Port

|--WaitForCompletion

Method Declaration

[Visual Basic]

Sub WaitForCompletion( )

[C++]

HRESULT WaitForCompletion( );

Parameters

None

Return Values

In Visual Basic, this method does not have a return value.

In C++, this method returns an HRESULT value, indicating success or failure.

Error Handling

In Visual Basic, if an error is raised, Err.Number is set to an HRESULT value.

In C++, if the call fails, an HRESULT value is returned.

Possible HRESULT values are documented in the Error Messages topic.

Requirements

Windows NT/2000: Windows 2000 SP2
Header: SkedCore.h
Library: XLANG Scheduler Runtime Type Library (SkedCore.dll)


Managing and Monitoring Reference

This section provides reference information about application programming interfaces (APIs) used by Microsoft BizTalk Server 2002 for both C++ and Microsoft Visual Basic programming.

Reference information is provided for all interfaces, methods, properties, and enumerations exposed for working with managing and monitoring BizTalk Server:

  • WMI Classes

In addition, a complete list of Error Messages is provided.


WMI Classes

The following COM interfaces are documented:

  • DocSuspendedEvent

  • InterchangeProvError

  • MicrosoftBizTalkServer_Group

  • MicrosoftBizTalkServer_GroupReceiveFunction

  • MicrosoftBizTalkServer_GroupServer

  • MicrosoftBizTalkServer_MgmtDB

  • MicrosoftBizTalkServer_Queue

  • MicrosoftBizTalkServer_ReceiveFunction

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_Server

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

  • MSBTS_CustomCounter

  • MSBTS_CustomCounterSetting

  • ReceiveFunctionDisabledEvent


DocSuspendedEvent

Represents events raised by documents sent to the Suspended queue.

Hierarchy

__ExtrinsicEvent

|--DocSuspendedEvent

Declaration

[Visual Basic]

Class DocSuspendedEvent

[C++]

class DocSuspendedEvent : __ExtrinsicEvent

Members

DocSuspendedEvent defines the following properties:

Property | Description
ChannelHandle | Contains the handle of the channel through which the suspended document was to be processed.
Destination | Contains the name of the destination organization to which the suspended document was to be processed.
DocName | Contains the name of the document definition designated as the input or output document for the channel through which the suspended document was to be processed.
PortHandle | Contains the handle of the messaging port attached to the channel through which the suspended document was to be processed.
Reason | Contains a value that indicates why the document was placed in the Suspended queue.
Source | Contains the name of the source organization from which the suspended document was to be processed.
State | Contains a value that indicates the state of the suspended document.
stringSuspendedGuid | Contains the tracking key of the item in the Suspended queue event.

Remarks

DocSuspendedEvent inherits from the __ExtrinsicEvent system class, an abstract base class that serves as a superclass for all user-defined event types.

The purpose of this event is to raise a notification when a document is delivered to the suspended queue because of a server processing error.

In the event that an administrator intentionally moves a document to the suspended queue using one of the following methods, a document suspended event will not be raised:

  • MoveToSuspendedQueue

  • MoveToSuspendedQueue

  • MoveToSuspendedQueue

Requirements

Windows NT/ Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ChannelHandle Property

Contains the handle of the channel through which the suspended document was to be processed.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ChannelHandle;

Parameters

None

Return Values

Returns the handle of the channel through which the suspended document was to be processed.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Destination Property

Contains the name of the destination organization to which the suspended document was to be processed.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Destination;

Parameters

None

Return Values

Returns the name of the destination organization to which the suspended document was to be processed.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocName Property

Contains the name of the document definition designated as the input or output document for the channel through which the suspended document was to be processed.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocName;

Parameters

None

Return Values

Returns the name of the document definition designated as the input or output document for the channel through which the suspended document was to be processed.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


PortHandle Property

Contains the handle of the messaging port attached to the channel through which the suspended document was to be processed.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 PortHandle;

Parameters

None

Return Values

Returns the handle of the messaging port attached to the channel through which the suspended document was to be processed.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Reason Property

Contains a value that indicates why the document was placed in the Suspended queue.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 Reason;

Parameters

None

Return Values

Returns a value that indicates why the document was placed in the Suspended queue. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value for this property corresponds to the Suspended queue Error Description column in BizTalk Server Administration. BizTalk Server Administration translates this value into an error string. For more information, see Suspended Queue.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Source Property

Contains the name of the source organization from which the suspended document was to be processed.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Source;

Parameters

None

Return Values

Returns the name of the source organization from which the suspended document was to be processed.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


State Property

Contains a value that indicates the state of the suspended document.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 State;

Parameters

None

Return Values

Returns a value that indicates the state of the suspended document. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The tables in this section show the possible processing states of a document or interchange in the Suspended queue.

Documents in the states listed in the following table are at the interchange level, so you should use the ViewInterchange method to view the data. In addition, interchanges in these states cannot be resubmitted, so in this case you should not call Resubmit.

Value | State
0 | Initial
1 | Custom component
2 | Parsing

Documents in the states listed in the following table are considered documents instead of interchanges, so you should use the ViewDocument method to view the data. In addition, documents in the document validation state (3) cannot be resubmitted, so for those documents you should not call Resubmit.

Value | State
3 | Document validation
4 | Channel selection
5 | Field tracking
6 | Correlating
7 | Mapping
8 | Serializing

Documents in the states listed in the following table are considered interchanges, so you should use the ViewInterchange method to view the data.

Value | State
9 | Encoding
10 | Signing
11 | Encrypting
12 | Transmitting

Note that the ViewErrorDescription method can be used to retrieve error description information about failed documents and interchanges.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


stringSuspendedGuid Property

Contains the tracking key of the item in the Suspended queue event.

Member List

DocSuspendedEvent

|--ChannelHandle

|--Destination

|--DocName

|--PortHandle

|--Reason

|--Source

|--State

|--stringSuspendedGuid

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string stringSuspendedGuid;

Parameters

None

Return Values

Returns the tracking key of the item in the Suspended queue event. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The tracking key of the item in the Suspended queue event is based on a GUID.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


InterchangeProvError

Represents error information returned by the interchange provider when creating class instances.

Hierarchy

__ExtendedStatus

|--InterchangeProvError

Declaration

[Visual Basic]

Class InterchangeProvError

[C++]

class InterchangeProvError : __ExtendedStatus

Members

InterchangeProvError defines the following property:

Property | Description
InterchangeProvName | Contains the name of the interchange provider returning error information.

Remarks

InterchangeProvError inherits from the __ExtendedStatus system class, which is used to report detailed status and error information.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


InterchangeProvName Property

Contains the name of the interchange provider returning error information.

Member List

InterchangeProvError

|--InterchangeProvName

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string InterchangeProvName;

Parameters

None

Return Values

Returns the name of the interchange provider returning error information.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_Group

Represents a logical grouping of a specific number of BizTalk Servers in an enterprise. It is the management abstraction for global BizTalk Server properties.

Hierarchy

MicrosoftBizTalkServer_Group

Declaration

[Visual Basic]

Class Group

[C++]

class MicrosoftBizTalkServer_Group

Members

MicrosoftBizTalkServer_Group defines the following properties:

Property | Description
ConfigurationCacheRefreshInterval | Contains a value that indicates how often the server refreshes the cache of the BizTalk Messaging Configuration objects, in seconds.
ConnectToDbStatus | Contains a value that indicates the status of the connection to the Tracking and Shared Queue databases.
DateModified | Contains a value that indicates the last modification date of the instance data.
DocTrackDbName | Contains the database name component of the connect string for the Tracking database.
DocTrackDbServer | Contains the server name component of the connect string for the Tracking database.
EnableDocumentTracking | Contains a value that indicates whether document tracking is enabled or disabled.
LoggingPointState | Contains a collection of flags that indicate the events that cause a Tracking entry to be logged.
Name | Contains the name of the server.
ParserOrder | Contains the CLSIDs of the parser components registered in the registry, sorted in parsing order.
ProxyHost | Contains the proxy host address.
ProxyLogon | Contains the proxy logon.
ProxyPassword | Contains the proxy password.
ProxyPort | Contains a value that indicates the proxy port number.
QueueDbName | Contains the database name component of the connect string for the Shared Queue database.
QueueDbServer | Contains the server name component of the connect string for the Shared Queue database.
ReliableMessagingReplyToURL | Contains the URL repository for reliable messaging.
RetryQueueCount | Contains a value that indicates the number of documents in the Retry queue.
ScheduledQueueCount | Contains a value that indicates the number of documents in the Scheduled queue.
SMTPHost | Contains the name of the Simple Mail Transfer Protocol (SMTP) host that is used for this group.
SuspendedQueueCount | Contains a value that indicates the number of documents in the Suspended queue.
UseProxyServer | Contains a value that indicates whether to use the proxy server.
WorkQueueCount | Contains a value that indicates the number of documents in the Work queue.

MicrosoftBizTalkServer_Group defines the following methods:

Method | Description
PurgeSuspendedQueue | Enables an administrator to remove all the documents in the Suspended queue.
RefreshParserListFromRegistry | Updates the list of parser components in the database, based on current components registered in the registry.

Remarks

MicrosoftBizTalkServer_Group is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ConfigurationCacheRefreshInterval Property

Contains a value that indicates how often the server refreshes the cache of the BizTalk Messaging Configuration objects, in seconds.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ConfigurationCacheRefreshInterval = 50;

Parameters

None

Return Values

Returns how often the server refreshes the cache of the BizTalk Messaging Configuration objects, in seconds.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

This property has a default value of 50.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ConnectToDbStatus Property

Contains a value that indicates the status of the connection to the Tracking and Shared Queue databases.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ConnectToDbStatus;

Parameters

None

Return Values

Returns the status of the connection to the Tracking and Shared Queue databases. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Permissible values for this property are "BothDbConnectOK", "DTAConnectFail", "SQConnectFail", and "BothConnectFail", which map to the integers 0, 1, 2, and 3, respectively. Note that the integer values must be used in code and script.

The following code is taken from the MOF file (InterchangeProvSchema.mof), and shows the mapping:

Values {"BothDbConnectOK", "DTAConnectFail", "SQConnectFail",

"BothConnectFail"},

ValueMap{"0", "1", "2", "3"}

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DateModified Property

Contains a value that indicates the last modification date of the instance data.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime DateModified;

Parameters

None

Return Values

Returns the last modification date of the instance data.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocTrackDbName Property

Contains the database name component of the connect string for the Tracking database.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocTrackDbName;

Parameters

None

Return Values

Returns the database name component of the connect string for the Tracking database.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 123 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocTrackDbServer Property

Contains the server name component of the connect string for the Tracking database.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocTrackDbServer;

Parameters

None

Return Values

Returns the server name component of the connect string for the Tracking database.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 60 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


EnableDocumentTracking Property

Contains a value that indicates whether document tracking is enabled or disabled.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean EnableDocumentTracking = 1;

Parameters

None

Return Values

Returns a language-specific value representing true if document tracking is enabled; if data tracking is not enabled, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is a language-specific value representing true.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


LoggingPointState Property

Contains a collection of flags that indicate the events that cause a Tracking entry to be logged.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 LoggingPointState;

Parameters

None

Return Values

Returns a collection of flags that indicate the events that cause a Tracking entry to be logged. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Permissible values for this property are "LogIncomingInterchange", "LogMIMEBlob", and "LogOutgoingInterchange", which map to the integers 0, 1, and 2, respectively. Note that the integer values must be used in code and script.

The following code is taken from the MOF file (InterchangeProvSchema.mof), and shows the mapping:

Values{"LogIncomingInterchange", "LogMIMEBlob",

"LogOutgoingInterchange" },

BitMap{"0", "1", "2"}

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the server.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

Returns the name of the server.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ParserOrder Property

Contains the CLSIDs of the parser components registered in the registry, sorted in parsing order.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ParserOrder[];

Parameters

None

Return Values

Returns the CLSIDs of the parser components registered in the registry, sorted in parsing order.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProxyHost Property

Contains the proxy host address.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProxyHost;

Parameters

None

Return Values

Returns the proxy host address.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProxyLogon Property

Contains the proxy logon.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProxyLogon;

Parameters

None

Return Values

Returns the proxy logon.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProxyPassword Property

Contains the proxy password.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProxyPassword;

Parameters

None

Return Values

Returns the proxy password.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-only. Due to security considerations, when you try to read this property, NULL is returned instead of the password value.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProxyPort Property

Contains a value that indicates the proxy port number.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ProxyPort = 80;

Parameters

None

Return Values

Returns the proxy port number.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is 80.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


PurgeSuspendedQueue Method

Enables an administrator to remove all the documents in the Suspended queue.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 PurgeSuspendedQueue();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


QueueDbName Property

Contains the database name component of the connect string for the Shared Queue database.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string QueueDbName;

Parameters

None

Return Values

Returns the database name component of the connect string for the Shared Queue database.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 123 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


QueueDbServer Property

Contains the server name component of the connect string for the Shared Queue database.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string QueueDbServer;

Parameters

None

Return Values

Returns the server name component of the connect string for the Shared Queue database.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 60 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


RefreshParserListFromRegistry Method

Updates the list of parser components in the database, based on current components registered in the registry.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 RefreshParserListFromRegistry();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ReliableMessagingReplyToURL Property

Contains the URL repository for reliable messaging.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ReliableMessagingReplyToURL;

Parameters

None

Return Values

Returns the URL repository for reliable messaging.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 512 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


RetryQueueCount Property

Contains a value that indicates the number of documents in the Retry queue.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 RetryQueueCount;

Parameters

None

Return Values

Returns the number of documents in the Retry queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ScheduledQueueCount Property

Contains a value that indicates the number of documents in the Scheduled queue.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ScheduledQueueCount;

Parameters

None

Return Values

Returns the number of documents in the Scheduled queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SMTPHost Property

Contains the name of the SMTP host that is used for this group.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SMTPHost;

Parameters

None

Return Values

Returns the name of the SMTP host that is used for this group.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SuspendedQueueCount Property

Contains a value that indicates the number of documents in the Suspended queue.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 SuspendedQueueCount;

Parameters

None

Return Values

Returns the number of documents in the Suspended queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


UseProxyServer Property

Contains a value that indicates whether to use the proxy server.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean UseProxyServer = 0;

Parameters

None

Return Values

Returns a language-specific value representing true if a proxy server is used; if a proxy server is not used, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is a language-specific value representing false.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


WorkQueueCount Property

Contains a value that indicates the number of documents in the Work queue.

Member List

MicrosoftBizTalkServer_Group

|--ConfigurationCacheRefreshInterval

|--ConnectToDbStatus

|--DateModified

|--DocTrackDbName

|--DocTrackDbServer

|--EnableDocumentTracking

|--LoggingPointState

|--Name

|--ParserOrder

|--ProxyHost

|--ProxyLogon

|--ProxyPassword

|--ProxyPort

|--PurgeSuspendedQueue

|--QueueDbName

|--QueueDbServer

|--RefreshParserListFromRegistry

|--ReliableMessagingReplyToURL

|--RetryQueueCount

|--ScheduledQueueCount

|--SMTPHost

|--SuspendedQueueCount

|--UseProxyServer

|--WorkQueueCount

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 WorkQueueCount;

Parameters

None

Return Values

Returns the number of documents in the Work queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_GroupReceiveFunction

Allows you to retrieve all the receive functions in a group.

Hierarchy

MicrosoftBizTalkServer_GroupReceiveFunction

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_GroupReceiveFunction

[C++]

class MicrosoftBizTalkServer_GroupReceiveFunction

Members

MicrosoftBizTalkServer_GroupReceiveFunction defines the following properties:

Property | Description
Antecedent | Contains references to the properties of the BizTalk Server group.
Dependent | Contains references to the properties of the receive function that is associated with the BizTalk Server group.

Remarks

MicrosoftBizTalkServer_GroupReceiveFunction is an association class.

Associations are instances of association classes and are used to represent relationships between other WMI objects.

MicrosoftBizTalkServer_GroupReceiveFunction is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Antecedent Property

Contains references to the properties of the BizTalk Server group.

Member List

MicrosoftBizTalkServer_GroupReceiveFunction

|--Antecedent

|--Dependent

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

MicrosoftBizTalkServer_Group ref Antecedent;

Parameters

None

Return Values

Returns a value that references the properties of the BizTalk Server group. The returned reference is to an instance of a MicrosoftBizTalkServer_Group object.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the Dependent property uniquely identifies an instance of the class.

This property is the parent component of an aggregation association.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Dependent Property

Contains references to the properties of the receive function that is associated with the BizTalk Server group.

Member List

MicrosoftBizTalkServer_GroupReceiveFunction

|--Antecedent

|--Dependent

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

MicrosoftBizTalkServer_ReceiveFunction ref Dependent;

Parameters

None

Return Values

Returns a value that references the properties of the receive function that is associated with the BizTalk Server group. The returned reference is to an instance of a MicrosoftBizTalkServer_ReceiveFunction object.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the Antecedent property uniquely identifies an instance of the class.

This property is the child component of an aggregation association.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_GroupServer

Allows you to retrieve all the servers in a group.

Hierarchy

MicrosoftBizTalkServer_GroupServer

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_GroupServer

[C++]

class MicrosoftBizTalkServer_GroupServer

Members

MicrosoftBizTalkServer_GroupServer defines the following properties:

Property | Description
Antecedent | Contains references to the properties of the BizTalk Server group.
Dependent | Contains references to the properties of the server that is associated with the BizTalk Server group.

Remarks

MicrosoftBizTalkServer_GroupServer is an association class.

Associations are instances of association classes and are used to represent relationships between other WMI objects.

MicrosoftBizTalkServer_GroupServer is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Antecedent Property

Contains references to the properties of the BizTalk Server group.

Member List

MicrosoftBizTalkServer_GroupServer

|--Antecedent

|--Dependent

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

MicrosoftBizTalkServer_Group ref Antecedent;

Parameters

None

Return Values

Returns a value that references the properties of the BizTalk Server group. The returned reference is to an instance of a MicrosoftBizTalkServer_Group object.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the Dependent property uniquely identifies an instance of the class.

This property is the parent component of an aggregation association.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Dependent Property

Contains references to the properties of the server that is associated with the BizTalk Server group.

Member List

MicrosoftBizTalkServer_GroupServer

|--Antecedent

|--Dependent

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

MicrosoftBizTalkServer_Server ref Dependent;

Parameters

None

Return Values

Returns a value that references the properties of the server that is associated with the BizTalk Server group. The returned reference is to an instance of a MicrosoftBizTalkServer_Server object.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the Antecedent property uniquely identifies an instance of the class.

This property is the child component of an aggregation association.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_MgmtDB

Represents the BizTalk Messaging Management database.

Hierarchy

MicrosoftBizTalkServer_MgmtDB

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_MgmtDB

[C++]

class MicrosoftBizTalkServer_MgmtDB

Members

MicrosoftBizTalkServer_MgmtDB defines the following properties:

Property | Description
LocalServer | Contains the name of the class, identifying the instance of the class.
MgmtDbName | Contains the initial catalog component of the BizTalk Messaging Management database connect string and represents the database name.
MgmtDbServer | Contains the data source part of the BizTalk Messaging Management database connect string.

Remarks

MicrosoftBizTalkServer_MgmtDB is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


LocalServer Property

Contains the name of the class, which identifies the instance of the class.

Member List

MicrosoftBizTalkServer_MgmtDB

|--LocalServer

|--MgmtDbName

|--MgmtDbServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string LocalServer;

Parameters

None

Return Values

Returns the name of the class, which identifies the instance of the class.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MgmtDbName Property

Contains the initial catalog component of the BizTalk Messaging Management database connect string and represents the database name.

Member List

MicrosoftBizTalkServer_MgmtDB

|--LocalServer

|--MgmtDbName

|--MgmtDbServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string MgmtDbName;

Parameters

None

Return Values

Returns the initial catalog component of the BizTalk Messaging Management database connect string and represents the database name.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 123 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MgmtDbServer Property

Contains the data source part of the BizTalk Messaging Management database connect string.

Member List

MicrosoftBizTalkServer_MgmtDB

|--LocalServer

|--MgmtDbName

|--MgmtDbServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string MgmtDbServer;

Parameters

None

Return Values

Returns the data source part of the BizTalk Messaging Management database connect string.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 60 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_Queue

Provides a set of properties inherited by Retry queue, Scheduled queue, Suspended queue, and Work queue objects.

Hierarchy

MicrosoftBizTalkServer_Queue

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_Queue

[C++]

class MicrosoftBizTalkServer_Queue

Members

MicrosoftBizTalkServer_Queue defines the following properties:

Property | Description
Destination | Contains the name of the organization or application that receives the document.
Group | Contains the name of the group to which the queue belongs.
QID | Contains a value that identifies an instance of the class.
Source | Contains the name of the organization or application that sends the document.
Timestamp | Contains a value that indicates the last time the document was used, or when it entered the queue.

Remarks

MicrosoftBizTalkServer_Queue serves only as a base for new classes. This class is abstract and should not be implemented.

The following interfaces inherit properties from MicrosoftBizTalkServer_Queue:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Destination Property

Contains the name of the organization or application that receives the document.

Member List

MicrosoftBizTalkServer_Queue

|--Destination

|--Group

|--QID

|--Source

|--Timestamp

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Destination;

Parameters

None

Return Values

Returns the name of the organization or application that receives the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 512 characters.

The following objects support this property:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Group Property

Contains the name of the group to which the queue belongs.

Member List

MicrosoftBizTalkServer_Queue

|--Destination

|--Group

|--QID

|--Source

|--Timestamp

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Group;

Parameters

None

Return Values

Returns the name of the group to which the queue belongs.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the QID property uniquely identifies an instance of the class.

The maximum length of this property is 256 characters.

The following objects support this property:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


QID Property

Contains a value that identifies an instance of the class.

Member List

MicrosoftBizTalkServer_Queue

|--Destination

|--Group

|--QID

|--Source

|--Timestamp

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 QID;

Parameters

None

Return Values

Returns a value that identifies an instance of the class.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property acts as a key for the class; its value along with the value of the Group property uniquely identifies an instance of the class.

The following objects support this property:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Source Property

Contains the name of the organization or application that sends the document.

Member List

MicrosoftBizTalkServer_Queue

|--Destination

|--Group

|--QID

|--Source

|--Timestamp

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Source;

Parameters

None

Return Values

Returns the name of the organization or application that sends the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 64 characters.

The following objects support this property:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Timestamp Property

Contains a value that indicates the last time the document was used or when it entered the queue.

Member List

MicrosoftBizTalkServer_Queue

|--Destination

|--Group

|--QID

|--Source

|--Timestamp

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime Timestamp;

Parameters

None

Return Values

Returns the last time the document was used or when it entered the queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

The following objects support this property:

  • MicrosoftBizTalkServer_RetryQueue

  • MicrosoftBizTalkServer_ScheduledQueue

  • MicrosoftBizTalkServer_SuspendedQueue

  • MicrosoftBizTalkServer_WorkQueue

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_ReceiveFunction

Represents a service that is set up on a BizTalk Server to handle incoming interchanges by using a specific protocol such as File, Message Queuing, or Script.

Hierarchy

MicrosoftBizTalkServer_ReceiveFunction

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_ReceiveFunction

[C++]

class MicrosoftBizTalkServer_ReceiveFunction

Members

MicrosoftBizTalkServer_ReceiveFunction defines the following properties:

Property | Description
ChannelName | Contains the name of the channel that the receive function should pass to the Submit method call when the pass-through flag is enabled.
Comment | Contains user comments.
DateModified | Contains a value that indicates the last modification date of the instance data.
DestinationID | Contains the ID of the organization or application that receives the document.
DestinationQualifier | Contains the ID type of the organization or application that receives the document.
DisableReceiveFunction | Contains a value that indicates whether to enable or disable the receive function.
DocumentName | Contains the name of the document definition for the input document of a channel.
EnvelopeName | Contains the name of an envelope definition instance in the BizTalk Messaging Management database.
FilenameMask | Contains the file name mask to use for receive functions that pull files from the file system for input to BizTalk Server.
GroupName | Contains the name of the group to which the server belongs.
HttpReturnContentType | Contains the name of the document type.
HttpReturnCorrelationToken | Contains a value that indicates whether to return a correlation token.
HttpTransportType | Contains the enumeration value used to represent the method used by the HTTP receive function to submit an interchange.
IsPassThrough | Contains a value that indicates whether a Submit method call is made with the pass-through flag enabled or disabled.
Name | Contains the name of the component.
OpennessFlag | Contains a value that indicates the value of the Openness parameter that the receive function passes to the Submit method.
Password | Contains the password to use for File Transfer Protocol (FTP) or Message Queuing receive functions that require a user name and password.
PollingLocation | Contains the name of the directory to poll (directory, message queue, and so on) for receive functions that require polling.
PreProcessor | Contains a value that indicates any preprocessing that must be done for a received document.
ProcessingServer | Contains the name of the server that is currently processing the interchange.
ProtocolType | Contains the enumeration value used to represent the type of the receive function component.
SourceID | Contains the ID of the organization or application that sends the document.
SourceQualifier | Contains the ID type of the organization or application that sends the document.
TransportURL | Contains the transport URL, indicating how and where the HTTP receive function submits the document.
Username | Contains the user name to use for FTP or Message Queuing receive functions.

Remarks

MicrosoftBizTalkServer_ReceiveFunction is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ChannelName Property

Contains the name of the channel that the receive function should pass to the Submit method call when the pass-through flag is enabled.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ChannelName;

Parameters

None

Return Values

Returns the name of the channel that the receive function should pass to the Submit method call when the pass-through flag is enabled. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 64 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Comment Property

Contains user comments.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Comment;

Parameters

None

Return Values

Returns user comments.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DateModified Property

Contains a value that indicates the last modification date of the instance data.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime DateModified;

Parameters

None

Return Values

Returns the last modification date of the instance data.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DestinationID Property

Contains the ID of the organization or application that receives the document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DestinationID;

Parameters

None

Return Values

Returns the ID of the organization or application that receives the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DestinationQualifier Property

Contains the ID type of the organization or application that receives the document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DestinationQualifier;

Parameters

None

Return Values

Returns the ID type of the organization or application that receives the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 64 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DisableReceiveFunction Property

Contains a value that indicates whether to enable or disable the receive function.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean DisableReceiveFunction = 0;

Parameters

None

Return Values

Returns a language-specific value representing true if the receive function is disabled; if the receive function is enabled, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is a language-specific value representing false.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocumentName Property

Contains the name of the document definition for the input document of a channel.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocumentName;

Parameters

None

Return Values

Returns the name of the document definition for the input document of a channel.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


EnvelopeName Property

Contains the name of an envelope definition instance in the BizTalk Messaging Management database.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string EnvelopeName;

Parameters

None

Return Values

Returns the name of an envelope definition instance in the BizTalk Messaging Management database.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


FilenameMask Property

Contains the file name mask to use for receive functions that pull files from the file system for input to BizTalk Server.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string FilenameMask;

Parameters

None

Return Values

Returns the file name mask to use for receive functions that pull files from the file system for input to BizTalk Server.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


GroupName Property

Contains the name of the group to which the server belongs.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string GroupName;

Parameters

None

Return Values

Returns the name of the group to which the server belongs.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


HttpReturnContentType Property

Contains the name of the document type.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string HttpReturnContentType;

Parameters

None

Return Values

Returns the name of the document type.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 64 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


HttpReturnCorrelationToken Property

Contains a value that indicates whether to return a correlation token.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean HttpReturnCorrelationToken = 0;

Parameters

None

Return Values

Returns a language-specific value representing true if the correlation token is returned; if the correlation token is not returned, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is a language-specific value representing false.

The maximum length of this property is 64 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


HttpTransportType Property

Contains the enumeration value used to represent the method used by the HTTP receive function to submit an interchange.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 HttpTransportType;

Parameters

None

Return Values

Returns the enumeration value used to represent the method used by the HTTP receive function to submit an interchange. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Permissible values for this property are "File", "Submit", and "SubmitSync", which map to the integers 1, 2, and 3, respectively. Note that the integer values must be used in code and script.

The following code is taken from the MOF file (InterchangeProvSchema.mof), and shows the values:

Values {"File", "Submit", "SubmitSync"}

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


IsPassThrough Property

Contains a value that indicates whether a Submit method call is made with the pass-through flag enabled or disabled.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean IsPassThrough = 0;

Parameters

None

Return Values

Returns a language-specific value representing true if the pass-through flag is enabled; if the pass-through flag is disabled, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is a language-specific value representing false.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the component.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

Returns the name of the component.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


OpennessFlag Property

Contains a value that indicates the value of the Openness parameter that the receive function passes to the Submit method.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 OpennessFlag;

Parameters

None

Return Values

Returns the value of the Openness parameter that the receive function passes to the Submit method. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Permissible values for this property are "NotOpen", "OpenSource", and "OpenDestination", which map to the integers 0, 1, and 2, respectively. Note that the integer values must be used in code and script.

The following code is taken from the MOF file (InterchangeProvSchema.mof), and shows the values:

Values {"NotOpen", "OpenSource", "OpenDestination"}

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Password Property

Contains the password to use for FTP or Message Queuing receive functions that require a user name and password.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Password;

Parameters

None

Return Values

Returns the password to use for FTP or Message Queuing receive functions that require a user name and password.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-only. Due to security considerations, when you try to read this property, NULL is returned instead of the password value.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


PollingLocation Property

Contains the name of the directory to poll (directory, message queue, and so on) for receive functions that require polling.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string PollingLocation;

Parameters

None

Return Values

Returns the name of the directory to poll (directory, message queue, and so on) for receive functions that require polling.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 260 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


PreProcessor Property

Contains a value that indicates any preprocessing that must be done for a received document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string PreProcessor;

Parameters

None

Return Values

Returns a value indicating any preprocessing that must be done for a received document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProcessingServer Property

Contains the name of the server that is currently processing the interchange.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProcessingServer;

Parameters

None

Return Values

Returns the name of the server that is currently processing the interchange.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProtocolType Property

Contains the enumeration value used to represent the type of the receive function component.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ProtocolType;

Parameters

None

Return Values

Returns the enumeration value used to represent the type of the receive function component. For more information, see "Remarks".

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Permissible values for this property are "File", "MSMQ", and "HTTP", which map to the integers 1, 2, and 3, respectively. Note that the integer values must be used in code and script.

The following code is taken from the MOF file (InterchangeProvSchema.mof), and shows the values:

Values {"File", "MSMQ", "HTTP"}

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SourceID Property

Contains the ID of the organization or application that sends the document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SourceID;

Parameters

None

Return Values

Returns the ID of the organization or application that sends the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SourceQualifier Property

Contains the ID type of the organization or application that sends the document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SourceQualifier;

Parameters

None

Return Values

Returns the ID type of the organization or application that sends the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 64 characters.

This property is provided for custom receive functions. The value of this property can be a phone number, a Dunn & Bradstreet number, and so on.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


TransportURL Property

Contains the transport URL, indicating how and where the HTTP receive function submits the document.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string TransportURL;

Parameters

None

Return Values

Returns the transport URL, indicating how and where the HTTP receive function submits the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

This property is provided for custom receive functions.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Username Property

Contains the user name to use for FTP or Message Queuing receive functions.

Member List

MicrosoftBizTalkServer_ReceiveFunction

|--ChannelName

|--Comment

|--DateModified

|--DestinationID

|--DestinationQualifier

|--DisableReceiveFunction

|--DocumentName

|--EnvelopeName

|--FilenameMask

|--GroupName

|--HttpReturnContentType

|--HttpReturnCorrelationToken

|--HttpTransportType

|--IsPassThrough

|--Name

|--OpennessFlag

|--Password

|--PollingLocation

|--PreProcessor

|--ProcessingServer

|--ProtocolType

|--SourceID

|--SourceQualifier

|--TransportURL

|--Username

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Username;

Parameters

None

Return Values

Returns the user name to use for FTP or Message Queuing receive functions.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_RetryQueue

Represents a logical grouping of interchanges in the Shared queue that are awaiting receipt correlation, or interchanges that are due to be sent to multiple destinations.

Hierarchy

MicrosoftBizTalkServer_Queue

|--MicrosoftBizTalkServer_RetryQueue

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_RetryQueue

[C++]

class MicrosoftBizTalkServer_RetryQueue: MicrosoftBizTalkServer_Queue

Members

MicrosoftBizTalkServer_RetryQueue defines the following properties:

Property | Description
Destination | Contains the name of the organization or application that receives the document.
Group | Contains the name of the group to which the queue belongs.
LastRetryTime | Contains a value that indicates the last time the server attempted a transmission.
ProcessingServer | Contains the name of the server that last processed the document.
QID | Contains a value that identifies an instance of the class.
RemainingRetryCount | Contains a value that indicates the number of outstanding retries remaining.
RetryInterval | Contains a value that indicates the wait time between retry intervals, in minutes.
ServiceWindowFromTime | Contains a value that indicates the start time of the service window in which to send interchanges.
ServiceWindowToTime | Contains a value that indicates the end time of the service window in which to send interchanges.
Source | Contains the name of the organization or application that sends the document.
Timestamp | Contains a value that indicates the last time the document was used, or when it entered the queue.

MicrosoftBizTalkServer_RetryQueue defines the following method:

Method | Description
MoveToSuspendedQueue | Enables the administrator to move the selected document to the Suspended queue.

Remarks

MicrosoftBizTalkServer_RetryQueue is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


LastRetryTime Property

Contains a value that indicates the last time the server attempted a transmission.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime LastRetryTime;

Parameters

None

Return Values

Returns the last time the server attempted a transmission.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MoveToSuspendedQueue Method

Enables the administrator to move the selected document to the Suspended queue.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 MoveToSuspendedQueue();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

Calling this method will not raise a DocSuspendedEvent.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProcessingServer Property

Contains the name of the server that last processed the document.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProcessingServer;

Parameters

None

Return Values

Returns the name of the server that last processed the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This is a read-only property.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


RemainingRetryCount Property

Contains a value that indicates the number of outstanding retries remaining.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 RemainingRetryCount;

Parameters

None

Return Values

Returns the number of outstanding retries remaining.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


RetryInterval Property

Contains a value that indicates the wait time between retry intervals, in minutes.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 RetryInterval;

Parameters

None

Return Values

Returns the wait time between retry intervals, in minutes.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ServiceWindowFromTime Property

Contains a value that indicates the start time of the service window in which to send interchanges.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime ServiceWindowFromTime;

Parameters

None

Return Values

Returns the start time of the service window in which to send interchanges.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ServiceWindowToTime Property

Contains a value that indicates the end time of the service window in which to send interchanges.

Member List

MicrosoftBizTalkServer_RetryQueue

|--LastRetryTime

|--MoveToSuspendedQueue

|--ProcessingServer

|--RemainingRetryCount

|--RetryInterval

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime ServiceWindowToTime;

Parameters

None

Return Values

Returns the end time of the service window in which to send interchanges.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_ScheduledQueue

Represents a logical grouping of interchanges in the Shared queue that are scheduled to be delivered at a later time based on a service window.

Hierarchy

MicrosoftBizTalkServer_Queue

|--MicrosoftBizTalkServer_ScheduledQueue

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_ScheduledQueue

[C++]

class MicrosoftBizTalkServer_ScheduledQueue: MicrosoftBizTalkServer_Queue

Members

MicrosoftBizTalkServer_ScheduledQueue defines the following properties:

Property | Description
Destination | Contains the name of the organization or application that receives the document.
Group | Contains the name of the group to which the queue belongs.
ProcessingServer | Contains the name of the server that last processed the document.
QID | Contains a value that identifies an instance of the class.
ServiceWindowFromTime | Contains a value that indicates the start time of the service window in which to send interchanges.
ServiceWindowToTime | Contains a value that indicates the end time of the service window in which to send interchanges.
Source | Contains the name of the organization or application that sends the document.
Timestamp | Contains a value that indicates the last time the document was used, or when it entered the queue.

MicrosoftBizTalkServer_ScheduledQueue defines the following method:

Method | Description
MoveToSuspendedQueue | Enables the administrator to move the selected document to the Suspended queue.

Remarks

MicrosoftBizTalkServer_ScheduledQueue is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MoveToSuspendedQueue Method

Enables the administrator to move the selected document to the Suspended queue.

Member List

MicrosoftBizTalkServer_ScheduledQueue

|--MoveToSuspendedQueue

|--ProcessingServer

|--ServiceWindowFromTime

|--ServiceWindowToTime

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 MoveToSuspendedQueue();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

Calling this method will not raise a DocSuspendedEvent.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProcessingServer Property

Contains the name of the server that last processed the document.

Member List

MicrosoftBizTalkServer_ScheduledQueue

|--MoveToSuspendedQueue

|--ProcessingServer

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProcessingServer;

Parameters

None

Return Values

Returns the name of the server that last processed the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ServiceWindowFromTime Property

Contains a value that indicates the start time of the service window in which to send interchanges.

Member List

MicrosoftBizTalkServer_ScheduledQueue

|--MoveToSuspendedQueue

|--ProcessingServer

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime ServiceWindowFromTime;

Parameters

None

Return Values

Returns the start time of the service window in which to send interchanges.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in interval format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ServiceWindowToTime Property

Contains a value that indicates the end time of the service window in which to send interchanges.

Member List

MicrosoftBizTalkServer_ScheduledQueue

|--MoveToSuspendedQueue

|--ProcessingServer

|--ServiceWindowFromTime

|--ServiceWindowToTime

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime ServiceWindowToTime;

Parameters

None

Return Values

Returns the end time of the service window in which to send interchanges.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in interval format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_Server

Represents specific Windows 2000 computers within a BizTalk Server group that are running BizTalk Messaging Services.

Hierarchy

MicrosoftBizTalkServer_Server

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_Server

[C++]

class MicrosoftBizTalkServer_Server

Members

MicrosoftBizTalkServer_Server defines the following properties:

Property | Description
DateModified | Contains the date of the last modification of the instance data.
GroupName | Contains the name of the group to which the server belongs.
MaxRecvSvcThreadsPerProcessor | Contains the maximum number of receive function threads that BizTalk Server can use per processor for asynchronous calls.
MaxWorkerThreadsPerProcessor | Contains the maximum number of worker threads that BizTalk Server can use per processor for asynchronous calls.
Name | Contains the name of the server.
ParticipateInWorkItemProcessing | Contains a value that indicates whether the server participates in work-item processing.
SchedulerWaitTime | Contains the time interval that BizTalk Server Scheduler waits between tries, in milliseconds.
ServiceState | Contains a value that indicates the state of the BizTalk services on a particular server.

MicrosoftBizTalkServer_Server defines the following methods:

Method | Description
FreeInterchanges | Frees interchanges that are currently assigned to a specific server if the server is stopped, removed, or in an error state, so that other servers can use these interchanges.
RegisterServerInAD | Registers the BizTalk Server in the Microsoft Active Directory.
StartServer | Starts the BizTalk services on a specific server.
StopServer | Stops the BizTalk services on a specific server.
UnregisterServerInAD | Unregisters the BizTalk Server in the Microsoft Active Directory.

Remarks

MicrosoftBizTalkServer_Server is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DateModified Property

Contains the date of the last modification of the instance data.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

datetime DateModified;

Parameters

None

Return Values

Returns the date of the last modification of the instance data.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The value of this property is in date and time format.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


FreeInterchanges Method

Frees interchanges that are currently assigned to a specific server if the server is stopped, removed, or in an error state, so that other servers can use these interchanges.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 FreeInterchanges();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


GroupName Property

Contains the name of the group to which the server belongs.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string GroupName;

Parameters

None

Return Values

Returns the name of the group to which the server belongs.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MaxRecvSvcThreadsPerProcessor Property

Contains the maximum number of receive function threads that BizTalk Server can use per processor for asynchronous calls.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 MaxRecvSvcThreadsPerProcessor = 4;

Parameters

None

Return Values

Returns the maximum number of receive function threads that BizTalk Server can use per processor for asynchronous calls.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is 4.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MaxWorkerThreadsPerProcessor Property

Contains the maximum number of worker threads that BizTalk Server can use per processor for asynchronous calls.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 MaxWorkerThreadsPerProcessor = 4;

Parameters

None

Return Values

Returns the maximum number of worker threads that BizTalk Server can use per processor for asynchronous calls.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is 4.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the server.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

Returns the name of the server.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ParticipateInWorkItemProcessing Property

Contains a value that indicates whether the server participates in work-item processing.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

boolean ParticipateInWorkItemProcessing = 1;

Parameters

None

Return Values

Returns a language-specific value representing true if the server participates in work-item processing; if the server does not participate in work-item processing, this property returns a language-specific value representing false.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is TRUE.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


RegisterServerInAD Method

Registers the BizTalk Server in the Microsoft Active Directory.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 RegisterServerInAD();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SchedulerWaitTime Property

Contains the time interval that BizTalk Server Scheduler waits between tries, in milliseconds.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 SchedulerWaitTime = 2000;

Parameters

None

Return Values

Returns the time interval that BizTalk Server Scheduler waits between tries, in milliseconds.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

The default value for this property is 2,000 milliseconds.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ServiceState Property

Contains a value that indicates the state of the BizTalk services on a particular server.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ServiceState;

Parameters

None

Return Values

Returns the state of the BizTalk services on a particular server.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


StartServer Method

Starts the BizTalk services on a specific server.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 StartServer();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

The execution of this method is valid any time the specific server is stopped.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


StopServer Method

Stops the BizTalk services on a specific server.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 StopServer();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

The execution of this method is valid any time the specific server is running.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


UnregisterServerInAD Method

Unregisters the BizTalk Server in the Microsoft Active Directory.

Member List

MicrosoftBizTalkServer_Server

|--DateModified

|--FreeInterchanges

|--GroupName

|--MaxRecvSvcThreadsPerProcessor

|--MaxWorkerThreadsPerProcessor

|--Name

|--ParticipateInWorkItemProcessing

|--RegisterServerInAD

|--SchedulerWaitTime

|--ServiceState

|--StartServer

|--StopServer

|--UnregisterServerInAD

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 UnregisterServerInAD();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_SuspendedQueue

Represents a logical grouping of interchanges in the Shared queue that could not be successfully processed.

Hierarchy

MicrosoftBizTalkServer_Queue

|--MicrosoftBizTalkServer_SuspendedQueue

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_SuspendedQueue

[C++]

class MicrosoftBizTalkServer_SuspendedQueue: MicrosoftBizTalkServer_Queue

Members

MicrosoftBizTalkServer_SuspendedQueue defines the following properties:

Property | Description
ChannelHandle | Contains the handle of the channel used for processing the interchange or document in the Suspended queue.
Destination | Contains the name of the organization or application that receives the document.
DocName | Contains the name of the document definition related to the document in the queue.
ErrorDescription | Contains the first 64 characters of the error description.
Group | Contains the name of the group to which the queue belongs.
QGUID | Contains the submission GUID of the Suspended queue work item.
QID | Contains a value that identifies an instance of the class.
Size | Contains the approximate size of the interchange or document in the Suspended queue, in bytes.
Source | Contains the name of the organization or application that sends the document.
State | Contains a value that indicates the state of the document or interchange in the Suspended queue.
Timestamp | Contains a value that indicates the last time the document was used, or when it entered the queue.

MicrosoftBizTalkServer_SuspendedQueue defines the following methods:

Method | Description
Resubmit | Enables an administrator to resubmit the selected document to the server.
ViewDocument | Enables an administrator to view the contents of a selected document in the Suspended queue.
ViewErrorDescription | Enables the administrator to view a description of the error.
ViewInterchange | Enables the administrator to view the contents of a selected interchange in the Suspended queue.

Remarks

MicrosoftBizTalkServer_SuspendedQueue is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ChannelHandle Property

Contains the handle of the channel used for processing the interchange or document in the Suspended queue.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 ChannelHandle;

Parameters

None

Return Values

Returns the handle of the channel used for processing the interchange or document in the Suspended queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocName Property

Contains the name of the document definition related to the document in the queue.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocName;

Parameters

None

Return Values

Returns the name of the document definition related to the document in the queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ErrorDescription Property

Contains the first 64 characters of the error description.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ErrorDescription;

Parameters

None

Return Values

Returns the first 64 characters of the error description.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 64 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


QGUID Property

Contains the submission GUID of the Suspended queue work item.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string QGUID;

Parameters

None

Return Values

Returns the submission GUID of the Suspended queue work item.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Resubmit Method

Enables an administrator to resubmit the selected document to the server.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 Resubmit();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This method enables an administrator to resubmit interchanges after problems have been fixed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Size Property

Contains the approximate size of the interchange or document in the Suspended queue, in bytes.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 Size;

Parameters

None

Return Values

Returns the approximate size of the interchange or document in the Suspended queue, in bytes.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


State Property

Contains a value that indicates the state of the document or interchange in the Suspended queue.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 State;

Parameters

None

Return Values

Returns the state of the document or interchange in the Suspended queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The tables in this section show the possible processing states of a document or interchange in the Suspended queue.

Documents in the states listed in the following table are at the interchange level, so you should use the ViewInterchange method to view the data. In addition, interchanges in these states cannot be resubmitted, so in this case you should not call Resubmit.

Value | State
0 | Initial
1 | Custom component
2 | Parsing

Documents in the states listed in the following table are considered documents instead of interchanges, so you should use the ViewDocument method to view the data. In addition, documents in the document validation state (3) cannot be resubmitted, so for those documents you should not call Resubmit.

Value | State
3 | Document validation
4 | Channel selection
5 | Field tracking
6 | Correlating
7 | Mapping
8 | Serializing

Documents in the states listed in the following table are considered interchanges, so you should use the ViewInterchange method to view the data.

Value | State
9 | Encoding
10 | Signing
11 | Encrypting
12 | Transmitting

Note that the ViewErrorDescription method can be used to retrieve error description information about failed documents and interchanges.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ViewDocument Method

Enables an administrator to view the contents of a selected document in the Suspended queue.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--QID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 ViewDocument(

uint8 Document[],

uint32 CodePage

);

Parameters

Document

[out] An array of bytes, representing the information in the document. This data may need to be converted into a readable format. The maximum size for this parameter is 4 MB. If the data exceeds 4 MB, the data will be truncated. For more information, see "Remarks".

CodePage

[out] The code page of the document. For more information, see "Remarks".

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

The following table shows the possible values for the CodePage parameter and their meanings.

Value | Description
-1 | No code page available
0 | Default system code page
1200 | Unicode code page
1252 | ASCII code page

If the value returned in the CodePage parameter is 0 or 1200, the data can be displayed and no conversion is needed. However, if the value is -1, you should try loading the data into Microsoft XML (MSXML).

If the value returned in CodePage is 1252, you should try loading the data into MSXML. If this fails, you can use the MultiByteToWideChar function, passing in CodePage as the code page parameter to the Microsoft Win32® API.

If the data contained in the Document parameter is larger than 4 MB, C++ programmers can use the GetSuspendedQueueItemDetails method to retrieve the document.

ViewDocument is not available in a tools-only installation of BizTalk Server 2002.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ViewErrorDescription Method

Enables the administrator to view a description of the error.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 ViewErrorDescription(

string CompleteErrorDescription

);

Parameters

CompleteErrorDescription

[out] A string describing the error.

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ViewInterchange Method

Enables the administrator to view the contents of a selected interchange in the Suspended queue.

Member List

MicrosoftBizTalkServer_SuspendedQueue

|--ChannelHandle

|--DocName

|--ErrorDescription

|--QGUID

|--Resubmit

|--Size

|--State

|--ViewDocument

|--ViewErrorDescription

|--ViewInterchange

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 ViewInterchange(

uint8 Interchange[],

uint32 CodePage

);

Parameters

Interchange

[out] An array of bytes, representing the information in the interchange. This data may need to be converted into a readable format. The maximum size for this parameter is 4 MB. If the data exceeds 4 MB, the data will be truncated. For more information, see "Remarks".

CodePage

[out] The code page of the interchange. For more information, see "Remarks".

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

The following table shows the possible values for the CodePage parameter and their meanings.

Value | Description
-1 | No code page available
0 | Default system code page
1200 | Unicode code page
1252 | ASCII code page

If the value returned in the CodePage parameter is 0 or 1200, the data can be displayed and no conversion is needed. However, if the value is -1, you should try loading the data into MSXML.

If the value returned in CodePage is 1252, you should try loading the data into MSXML. If this fails, you can use the MultiByteToWideChar function, passing in CodePage as the codepage parameter to the Win32 API.

If the data contained in the Interchange parameter is larger than 4 MB, C++ programmers can use the GetSuspendedQueueItemDetails method to retrieve the interchange.

ViewInterchange is not available in a tools-only installation of BizTalk Server 2002.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MicrosoftBizTalkServer_WorkQueue

Represents a logical grouping of interchanges in the Shared queue that are currently in process.

Hierarchy

MicrosoftBizTalkServer_Queue

|--MicrosoftBizTalkServer_WorkQueue

Declaration

[Visual Basic]

Class MicrosoftBizTalkServer_WorkQueue

[C++]

class MicrosoftBizTalkServer_WorkQueue: MicrosoftBizTalkServer_Queue

Members

MicrosoftBizTalkServer_WorkQueue defines the following properties:

Property | Description
Destination | Contains the name of the organization or application that receives the document.
DocName | Contains the name of the document definition related to the document in the queue.
EngineState | Contains a value that indicates whether the work item is waiting for receipt correlation or waiting for transmission.
Group | Contains the name of the group to which the queue belongs.
ProcessingServer | Contains the name of the server that last processed the document.
QID | Contains a value that identifies an instance of the class.
Source | Contains the name of the organization or application that sends the document.
Timestamp | Contains a value that indicates the last time the document was used, or when it entered the queue.

MicrosoftBizTalkServer_WorkQueue defines the following method:

Method | Description
MoveToSuspendedQueue | Enables the administrator to move the selected document to the Suspended queue.

Remarks

MicrosoftBizTalkServer_WorkQueue is a dynamic class, supplied by the WMI provider "InterchangeProv" at run time as needed.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocName Property

Contains the name of the document definition related to the document in the queue.

Member List

MicrosoftBizTalkServer_WorkQueue

|--DocName

|--EngineState

|--MoveToSuspendedQueue

|--ProcessingServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocName;

Parameters

None

Return Values

Returns the name of the document definition related to the document in the queue.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


EngineState Property

Contains a value that indicates whether the work item is waiting for receipt correlation or waiting for transmission.

Member List

MicrosoftBizTalkServer_WorkQueue

|--DocName

|--EngineState

|--MoveToSuspendedQueue

|--ProcessingServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 EngineState;

Parameters

None

Return Values

Returns a value that indicates whether the work item is waiting for receipt correlation or waiting for transmission.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The possible values for this property are defined by the BTSCoreQueueStates enumeration, as shown in the following code:

typedef enum {

Processing = STATE_TRANSLATION,

Correlation = STATE_RECEIPT_CORRELATION,

TransmissionWServiceWindow = STATE_FIND_TRANSMISSION,

Transmission = STATE_TRANSMISSION

} BTSCoreQueueStates;

The following table provides the numerical values of the constants defined in the BTSCoreQueueStates enumeration.

Value | Constant
29 | Processing
30 | Correlation
31 | TransmissionWServiceWindow
33 | Transmission

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MoveToSuspendedQueue Method

Enables the administrator to move the selected document to the Suspended queue.

Member List

MicrosoftBizTalkServer_WorkQueue

|--DocName

|--EngineState

|--MoveToSuspendedQueue

|--ProcessingServer

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

type name;

uint32 MoveToSuspendedQueue();

Parameters

None

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

Calling this method will not raise a DocSuspendedEvent.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ProcessingServer Property

Contains the name of the server that last processed the document.

Member List

MicrosoftBizTalkServer_WorkQueue

|--DocName

|--EngineState

|--MoveToSuspendedQueue

|--ProcessingServer

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string ProcessingServer;

Parameters

None

Return Values

Returns the name of the server that last processed the document.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

The maximum length of this property is 63 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MSBTS_CustomCounter

Retrieves the value of the custom counter query.

Hierarchy

CIM_ManagedSystemElement

|--CIM_LogicalElement

|--MSBTS_CustomCounter

Declaration

[Visual Basic]

Class MSBTS_CustomCounter

[C++]

class MSBTS_CustomCounter : CIM_LogicalElement

Members

MSBTS_CustomCounter defines the following properties:

Property | Description
GroupCounterName | Contains the Tracking database and custom counter names.
MatchCount | Contains the number of documents that match the criteria specified by the custom counter setting.
Name | Contains the name of the custom counter.

Remarks

MSBTS_CustomCounter is derived from CIM_LogicalElement.

MSBTS_CustomCounter is a dynamic class that is automatically created for every instance of MSBTS_CustomCounterSetting.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


GroupCounterName Property

Contains the Tracking database and custom counter names.

Member List

MSBTS_CustomCounter

|--GroupCounterName

|--MatchCount

|--Name

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string GroupCounterName;

Parameters

None

Return Values

This property returns the Tracking database and custom counter names.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

For a custom counter with a GroupName property of "BizTalk Server Group" and a Name property of "My Custom Counter", the value for this property would be "BizTalk Server Group\MyCustomCounter".

This property is required to distinguish between custom counters with the same name that monitor different DTA databases.

The maximum length of this property is 256 characters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MatchCount Property

Contains the number of documents that match the criteria specified by the custom counter setting.

Member List

MSBTS_CustomCounter

|--GroupCounterName

|--MatchCount

|--Name

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 MatchCount;

Parameters

None

Return Values

This property returns the number of documents that match the query associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read-only.

Note that this property counts both inbound and outbound documents. For example, if a single document passes through the system and no mapping is performed, then MatchCount will be incremented by two.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the custom counter.

Member List

MSBTS_CustomCounter

|--GroupCounterName

|--MatchCount

|--Name

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

This property returns the name of the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

Both MSBTS_CustomCounter and MSBTS_CustomCounterSetting share the same value for their key property, Name.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


MSBTS_CustomCounterSetting

Creates, deletes, and validates custom counters.

Hierarchy

CIM_Setting

|--MSBTS_CustomCounterSetting

Declaration

[Visual Basic]

Class MSBTS_CustomCounterSetting

[C++]

class MSBTS_CustomCounterSetting : CIM_Setting

Members

MSBTS_CustomCounterSetting defines the following properties:

Property | Description
DestOrgName | Contains the name of the destination organization associated with the custom counter.
DestQualifier | Contains the name of the destination qualifier type associated with the custom counter.
DestQualifierValue | Contains the value of the destination qualifier type associated with the custom counter.
DocType | Contains the name of the root element from the document schema.
GroupName | Contains the name of the BizTalk Server group against which the custom counter query executes.
Name | Contains the name of the custom counter.
SrcOrgName | Contains the name of the source organization associated with the custom counter.
SrcQualifier | Contains the name of the source qualifier type associated with the custom counter.
SrcQualifierValue | Contains the value of the source qualifier type associated with the custom counter.
TimeInterval | Contains the time over which to accumulate the custom counter query value, in seconds.

MSBTS_CustomCounterSetting defines the following method:

Method | Description
IsValid | Validates the custom counter creation parameters.

Remarks

MSBTS_CustomCounterSetting is derived from CIM_Setting.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DestOrgName Property

Contains the name of the destination organization associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DestOrgName;

Parameters

None

Return Values

This property returns the name of the destination organization associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

When the destination information is not explicitly declared in the messaging port the string value that is tracked for DstOrgName is "<OPEN DESTINATION>". For more information, see How Interchanges and Documents Are Logged.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DestQualifier Property

Contains the name of the destination qualifier type associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DestQualifier;

Parameters

None

Return Values

This property returns the name of the destination qualifier type associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DestQualifierValue Property

Contains the value of the destination qualifier type associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DestQualifierValue;

Parameters

None

Return Values

This property returns the value of the destination qualifier type associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


DocType Property

Contains the name of the root element from the document schema.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string DocType;

Parameters

None

Return Values

This property returns the name of the root element from the document schema.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

When a document specification is created using BizTalk Editor, you can specify the Document Type reference property to a user-defined string value. If the root XML element is not defined, the value of the Document Type reference property, if defined, will be tracked as the DocType value. For more information, see Set Reference Properties.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


GroupName Property

Contains the name of the BizTalk Server group against which the custom counter query executes.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string GroupName;

Parameters

None

Return Values

This property returns the name of the BizTalk Server group against which the custom counter query executes.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property is used to look up the database name, server, user name, and password, and to validate the custom counter parameters.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


IsValid Method

Validates the custom counter creation parameters.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Method Declaration

The syntax shown is language neutral. This method is supported in C++, Visual Basic, and VBScript.

uint32 IsValid(

boolean IsValidSrcOrg,

boolean IsValidSrcId,

boolean IsValidDestOrg,

boolean IsValidDestId,

boolean IsValidGroup

);

Parameters

IsValidSrcOrg

[out] Returns a language-specific value representing true if the source organization name is valid; otherwise, if the source organization name is not valid, this parameter returns a language-specific value representing false.

IsValidSrcId

[out] Returns a language-specific value representing true if the source identifier name is valid; otherwise, if the source identifier name is not valid, this parameter returns a language-specific value representing false.

IsValidDestOrg

[out] Returns a language-specific value representing true if the destination organization name is valid; otherwise, if the destination organization name is not valid, this parameter returns a language-specific value representing false.

IsValidDestId

[out] Returns a language-specific value representing true if the destination identifier name is valid; otherwise, if the destination identifier name is not valid, this parameter returns a language-specific value representing false.

IsValidGroup

[out] Returns a language-specific value representing true if the BizTalk Server group name is valid; otherwise, if the BizTalk Server group name is not valid, this parameter returns a language-specific value representing false.

Return Values

Returns an HRESULT value, indicating success or failure.

Error Handling

For information on error handling, see Handling WMI Errors.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

This property returns the name of the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

The value of this property acts as the key for the class; its value uniquely identifies an instance of the class.

The maximum length of this property is 256 characters.

Both MSBTS_CustomCounterSetting and MSBTS_CustomCounter share the same value for their key property, Name.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SrcOrgName Property

Contains the name of the source organization associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SrcOrgName;

Parameters

None

Return Values

This property returns the name of the source organization associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

When the source information is not explicitly declared in the channel, the string value that is tracked for SrcOrgName is "<OPEN SOURCE>". For more information, see How Interchanges and Documents Are Logged.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SrcQualifier Property

Contains the name of the source qualifier type associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SrcQualifier;

Parameters

None

Return Values

Returns the name of the source qualifier type associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


SrcQualifierValue Property

Contains the value of the source qualifier type associated with the custom counter.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string SrcQualifierValue;

Parameters

None

Return Values

Returns the value of the source qualifier type associated with the custom counter.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This property can accept a regular expression.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


TimeInterval Property

Contains the time over which to accumulate the custom counter query value, in seconds.

Member List

MSBTS_CustomCounterSetting

|--DestOrgName

|--DestQualifier

|--DestQualifierValue

|--DocType

|--GroupName

|--IsValid

|--Name

|--SrcOrgName

|--SrcQualifier

|--SrcQualifierValue

|--TimeInterval

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

uint32 TimeInterval;

Parameters

None

Return Values

Returns the time over which to accumulate the custom counter query value, in seconds.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is read/write.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: InterchangeProvSchema.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


ReceiveFunctionDisabledEvent

Represents events raised by disabled receive functions.

Hierarchy

__ExtrinsicEvent

|--ReceiveFunctionDisabledEvent

Declaration

[Visual Basic]

Class ReceiveFunctionDisabledEvent

[C++]

class ReceiveFunctionDisabledEvent : __ExtrinsicEvent

Members

ReceiveFunctionDisabledEvent defines the following property:

Property | Description
Name | Contains the name of the disabled receive function.

Remarks

ReceiveFunctionDisabledEvent inherits from the __ExtrinsicEvent system class, an abstract base class that serves as a superclass for all user-defined event types.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Name Property

Contains the name of the disabled receive function.

Member List

ReceiveFunctionDisabledEvent

|--Name

Property Declaration

The syntax shown is language neutral. This property is supported in C++, Visual Basic, and VBScript.

string Name;

Parameters

None

Return Values

Returns the name of the disabled receive function.

Error Handling

For information on error handling, see Handling WMI Errors.

Remarks

This property is write-on-create only. After creation, this property is read-only.

This event is raised when a receive function is disabled.

Requirements

Windows NT/Windows 2000: Windows 2000 SP2
Header and Library: Wbemidl.h, Wbemuuid.lib
MOF File: SrvEvents.mof
Scripting Library: Microsoft WMI Scripting V1.1 Library (wbemdisp.tlb)


Error Messages

The properties and methods of the BizTalk™ Messaging Services and BizTalk Orchestration Services object models use standard Component Object Model (COM) HRESULT return values to communicate whether the operation was successful or not.

In C++, these values are the actual return values from the methods themselves (including property get_ and put_ methods). The program must explicitly perform error checking by examining these return values, or use some variation of structured error handling.

In Microsoft® Visual Basic®, and in Microsoft Visual Basic Scripting Edition (VBScript), these values are placed in the Number property of the global Err object. Error handling is either handled automatically, displaying a standard error dialog box, or explicitly by the program, checking the value of the Number property of the global Err object. The On Error Resume Next command disables automatic error handling, thereby enabling explicit error handling.

For additional information about error message values, see the following sections:

  • Messaging Services Error Messages

  • Orchestration Services Error Messages

  • Standard COM Error Messages


Messaging Services Error Messages

The BizTalk Messaging Services object model error messages defined by BizTalk Server can be used in your application by including the bts_config_errors.h file located in the BizTalk Server installation directory at \Program Files\Microsoft BizTalk Server\SDK\Include. These error messages, returned during design time by the methods and properties of the object model, contain a BTS_ prefix in the message name. All other errors occur during run time, while BizTalk Server is processing a document.

The following table contains both design time and run time errors.

Message name | Value | Description
CIS_E_OBJECT_NOT_FOUND | 0x0100 | The object was not found.
CIS_E_STATE_NOT_FOUND | 0x0101 | The state engine state was not found in the messaging port definition.
CIS_E_STATE_TRANSITION | 0x0103 | The state table contains a bad engine state transition.
CIS_E_BAD_ENGINE_CONFIG_FILE | 0x0105 | The string that describes the input state configuration is not valid.
CIS_E_CANNOT_ADD_STATE | 0x0106 | BizTalk Server could not add the user-defined state to the system.
CIS_E_NO_COMPONENT_FOUND | 0x0107 | There is no component in the state definition or the ProgID is wrong.
CIS_E_PIPECOMP_ADMIN_REQUIRED | 0x0108 | The required IPipelineComponentAdmin interface was not found on the component.
CIS_E_BAD_COMPONENT_TYPE | 0x0109 | The component type specified for the state engine is not recognized.
CIS_E_BAD_STATE_CONFIG | 0x010A | The state configuration is not valid.
CIS_E_BAD_STATE_TYPE | 0x010B | The specified state type is not recognized.
CIS_E_BAD_COMPONENT_CONFIG | 0x010C | The component configuration is not valid.
CIS_E_INTERNAL_FAILURE | 0x010F | An internal server failure occurred due to an unknown cause.
CIS_E_CREATE_SCHEDULER_FAILED | 0x0111 | The Queue Scheduler for the service could not be created.
CIS_E_AGREEMENT_SELECT_FAILED | 0x0112 | No channels matched the input criteria. Verify that a messaging port and a channel exist, and that they match the following fields: Source qualifier: "%1" Source identifier value: "%2" Source document name: "%3" Destination qualifier: "%4" Destination identifier value: "%5" Also verify that any expressions specified for the channels are compatible with this document.
CIS_E_ERROR | 0x0113 | An error occurred in BizTalk Server.%n %n Details:%n ------------------------------%n %1
CIS_E_SERVICE_INITIALIZATION_FAILURE | 0x0114 | The service failed to start. Verify that this server is enlisted in a BizTalk Server group.
CIS_E_SCHEDULER_FAILED | 0x0115 | The Queue Scheduler failed and has exited.
CIS_E_WORKER_THREAD_FAILED | 0x0116 | A worker thread failed and has exited.
CIS_E_SHARED_QUEUE_DB_EXEC_FAILED | 0x0117 | Execution against the Shared Queue database has failed.
CIS_E_CANT_READ_WORK_ITEM | 0x0119 | A work item in the Shared Queue database cannot be read.
CIS_E_CHECKPOINT_FAILED | 0x011c | Checkpointing the work item failed.
CIS_E_CREATE_DEAD_WORK_ITEM_FAILED | 0x011e | A new work item in the Suspended queue cannot be created.
CIS_E_GET_SNAPSHOT_FAILED | 0x0122 | A snapshot of the Shared Queue database cannot be taken.
CIS_E_FREE_INTERCHANGES_FAILED | 0x0124 | The specified interchanges cannot be freed.
CIS_E_DELETE_INTERCHANGE_FAILED | 0x0125 | The specified interchange cannot be deleted.
CIS_E_RECEIVING_INTERCHANGE_FAILED | 0x0127 | The specified interchange was not received.
CIS_E_GETTING_NEXT_SCHEDULED_WORK_ITEM_FAILED | 0x0128 | The next scheduled work item cannot be obtained for processing.
CIS_E_GET_COUNT_FAILED | 0x0129 | The count on the shared queues cannot be obtained.
CIS_E_TRANSMISSION_FAILED | 0x012a | All retry transmissions failed.
CIS_W_TRANSMISSION_ATTEMPT_FAILED | 0x012b | A transmission attempt failed.
CIS_W_TRANSMISSION_XFER_TO_SECONDARY | 0x012c | The primary transport for messaging port "%1" cannot transmit the data. The server will switch to the secondary transport.
CIS_E_RECEIPT_GENERATION_FAILED | 0x012e | After creating the work item, the attempt to generate a receipt failed.
CIS_E_RECEIPT_GENERATION_FAILED_NO_WORK_ITEM | 0x012f | The attempt to generate a receipt failed before the work item was created.
CIS_E_L1_RECEIPT_CORRELATION_FAILED | 0x0130 | Receipt correlation failed.
CIS_E_AGREEMENT_LACKING_PARAMS | 0x0133 | At least one of the fields necessary to select a channel is missing. Verify that your document and envelopes extract the proper fields for the parser, or specify the necessary fields upon submission. Channel selection fields: Source identifier type: "%1" Source identifier value: "%2" Source document name: "%3" Destination identifier type: "%4" Destination identifier value: "%5"
CIS_E_AGREEMENT_FAILED | 0x0134 | The channel cannot be selected.
CIS_E_ORIGINAL_L1_INTERCHANGE_MISSING | 0x0135 | When trying to correlate an incoming receipt, the original interchange and related document(s) are no longer present.
CIS_E_UNEXPECTED_DB_BEHAVIOR | 0x0136 | An unexpected return occurred. The database may need to be restarted.
CIS_E_AGREEMENT_INVALID_MAP | 0x0137 | The map specified by the reference "%1" is not valid. Verify that the reference points to a valid map created by BizTalk Mapper.
CIS_I_SERVICE_MSG | 0x0138 | 1%
CIS_E_AGREEMENT_MAP_FAILED | 0x0139 | The XML document could not be translated. The map specified by reference "%1" failed. Verify that the map is up to date.
CIS_E_XML_ERROR | 0x013A | The XML document could not be parsed on line: %2, position: %3 for the following reason: "%1"
CIS_E_AGREEMENT_PROCESSING_FAILED | 0x013f | The server could not finish processing the document.
CIS_E_AGREEMENT_PROCESSING_FAILED_W_NAME | 0x0140 | The following channel configuration setting is not valid: "%1"
CIS_E_AGREEMENT_INVALID_QUERY | 0x0141 | The "%2" query for the "%1" document tracking field is not a valid XSL pattern. This pattern must be removed or corrected.
CIS_I_SERVICE_START | 0x0142 | The service has started.
CIS_I_SERVICE_STOP | 0x0143 | The service has stopped.
CIS_E_ERROR_EX | 0x0144 | An error occurred in BizTalk Server.%n %n Details:%n ------------------------------%n %1 %2 %3 %4 %5 %6 %7 %8 %9 %n
CIS_E_ERROR_EX_HEAD | 0x0145 | An error occurred in BizTalk Server.
CIS_E_ERROR_EX_FOOT | 0x0146 |
CIS_E_INVALID_DATA_FORMAT | 0x0147 | The business document that was passed in is not in a recognized format and could not be parsed or decrypted.
CIS_E_CREATE_ENGINE | 0x0148 | BizTalk Server was unable to create a new instance of the processing engine to process a work item. This might be due to a failure to create a new COM+ transaction.
CIS_E_MISSING_DESTINATION_DOCUMENT_SPEC | 0x0149 | BizTalk Server has detected an incomplete messaging port. The destination specification is missing from the messaging port.
CIS_E_PROCESSING_THREAD_FAILED | 0x014A | The processing thread failed to start. This might be due to a failure to create the state engine.
CIS_E_NOSRCORG | 0x014B | No source organization that corresponds to the ID and Qualifier pair has been specified.
CIS_E_NODESTORG | 0x014C | No destination organization that corresponds to the Identifier and Qualifier pair has been specified.
CIS_E_NODOC | 0x014D | No document that corresponds to the document name has been specified.
CIS_E_NOPIPELINES | 0x014E | No channel that corresponds to the parameters has been specified.
CIS_E_NOT_RESUBMITTABLE | 0x014F | The state of the item in the Suspended queue does not allow resubmission.
CIS_E_PIPESELECT_POLICY_FAILED | 0x0150 | No channels matched the certificates that were found with the incoming data. The following certificates accompanied the submitted data: Signature certificate reference: "%1" Encryption certificate reference: "%2"
CIS_E_SUBMIT_INVALIDDOC | 0x0151 | The submitted document is not valid. See the following messages for more details.
CIS_E_SUBMITSYNC_TOOMANYDOCS | 0x0152 | The SubmitSync method failed because multiple documents where found within the data. Only one document is allowed per synchronous submission. If this is a structured flat-file submission, then the most common cause of failure is extra leading or trailing white space around the data.
CIS_E_SUBMITSYNC_TOOMANYPIPES | 0x0153 | The synchronous submission could not be completed because multiple valid channels matched the incoming document. Only one channel is allowed to match the incoming document.
CIS_E_XMIT_NOTRANSPORTCOMP | 0x0154 | This server could not create a component with the class ID "%1" for transport. Verify that this component is properly registered. The following error was returned:
CIS_E_XMIT_EMPTY_DOCUMENT | 0x0155 | Messaging port "%1" cannot transmit a zero-byte document.
CIS_E_XMIT_FAILED_W_NAME | 0x0156 | The server could not finish processing messaging port "%1".
CIS_E_XMIT_NO_INTERFACE | 0x0157 | The server could not obtain the "%1" interface from the transport component with CLSID "%2".
CIS_E_XMIT_NO_BTS_AIC_INTERFACES | 0x0158 | The server could not obtain either the "%1" or "%2" interfaces from the BizTalk Server application integration component with CLSID "%3".
CIS_E_XMIT_FAILED_W_DETAILS | 0x0159 | The server encountered a transport error while processing the messaging port "%1", which uses a transport component with a ProgID of "%2".
CIS_E_NOHDR_ERROR_EX | 0x015A | %1 %2 %3 %4 %5 %6 %7 %8 %9 %n
CIS_W_COMP_NOACK | 0x015B | The correlation component "%1" could not find a document for which to send a receipt. No action will be taken.
CIS_E_CORRELATIONCOMP_FAILED | 0x015C | The correlation component "%1" returned an unexpected failure. The document will be placed in the Suspended queue.
CIS_E_CORRELATION_FAILED | 0x015D | Receipt correlation processing failed.
CIS_E_XML_VALIDATE_ERROR | 0x015E | The XML document has failed validation for the following reason: %1
CIS_E_CHANNEL_ACCESSDENIED | 0x015F | The submitted document does not have the necessary signature or encryption required by channel "%3". The following certificates accompanied the submitted data: Signature certificate reference: "%1" Encryption certificate reference: "%2"
CIS_I_SERVICE_RESTARTING | 0x0160 | The service is restarting.
BTS_E_CONSTRAINT | 0x1201 | Constraint Error
BTS_E_NOOBJECT | 0x1202 | The object was not found.
BTS_E_INTERNALFAILURE | 0x1203 | An internal failure occurred.
BTS_E_ENVELOPE_CONTROLNUMBER | 0x120C | If the envelope format is set to X12 or EDIFACT, the control number value must be set to a number greater than or equal to 1.
BTS_E_ENVELOPE_DELIMETER | 0x120D | If the envelope format is set to X12, then delimiters are required and must be set.
BTS_E_ENCRYPTION_CUSTOM_NOCLSID | 0x120E | If the encryption type is Custom, then the class identifier (CLSID) must also be specified.
BTS_E_ENCODING_CUSTOM_NOCLSID | 0x120F | If the encoding type is Custom, then the class identifier (CLSID) must also be specified.
BTS_E_SIGNATURE_CUSTOM_NOCLSID | 0x1210 | If the signature type is Custom, then the class identifier (CLSID) must also be specified.
BTS_E_INVALIDCONTROLNUMBER | 0x1212 | The control number value must be set to a number greater than or equal to 1.
BTS_E_ENVELOPE_INUSE | 0x1213 | The format of the envelope cannot be changed because it is used in a messaging port.
BTS_E_CHANNEL_MISSINGMAPSOURCE | 0x1215 | The channel is missing the MapSource node.
BTS_E_INVALID_CERT_USAGE | 0x1216 | The certificate is not valid for the current usage. An encryption certificate cannot be used for signing; nor can a signing certificate be used for encryption. Make sure that the correct certificate is selected.
BTS_E_MISSINGSMTPHOST | 0x1218 | The SMTP host is missing. The SMTP host can be configured in BizTalk Server Administration.
BTS_E_INVALID_ENCRYPT_STORE | 0x1219 | The encryption store type is not valid. The store type must be BIZTALK.
BTS_E_INVALID_SGNTCERT_STORE | 0x121A | The signature store type is not valid. The store type must be MY.
BTS_E_DATATOOLONG | 0x121B | The data length is too long.
BTS_E_INVALID_VERIFY_ENCRYPTCERT_STORE | 0x121C | The encryption verification store type is not valid. The store type must be MY.
BTS_E_INVALID_VERIFY_SGNTCERT_STORE | 0x121D | The signature verification store type is not valid. The store type must be BIZTALK.
BTS_E_ORGANIZATION_UNIQUE_ID | 0x121F | The organization identifier must be a unique identifier.
BTS_E_ORGANIZATION_UNIQUE_NAME | 0x1220 | The organization name must be a unique name.
BTS_E_OBJECT_ALREADY_EXISTS | 0x1221 | The object already exists. You cannot call the Create() method on a BizTalk Messaging Configuration object multiple times without also calling the Clear() or Remove() methods.
BTS_E_ALIAS_UNIQUE_ID | 0x1222 | The identifier must be a unique identifier.
BTS_E_ALIAS_UNIQUE_NAME | 0x1223 | The identifier name for this organization must be a unique name.
BTS_E_ALIAS_UNIQUE_QUALIFIERVALUE | 0x1225 | The identifier must have a unique qualifier-value pair.
BTS_E_ALIAS_FOREIGN_OWNERID | 0x1226 | The organization cannot be removed because it is referred to by an identifier.
BTS_E_XMLSHARE_UNIQUE_ID | 0x1227 | The primary identifier for the XML Share table in the SQL Server database must be a unique identifier.
BTS_E_XMLSHARE_UNIQUE_REFERENCE | 0x1228 | The reference for the XML Share table in the SQL Server database must be a unique reference.
BTS_E_DOCUMENT_UNIQUE_ID | 0x1229 | The document identifier must be a unique identifier.
BTS_E_DOCUMENT_UNIQUE_NAME | 0x122A | The document name must be a unique name.
BTS_E_DOCUMENT_FOREIGN_SHAREID | 0x122C | The XML Share table in the SQL Server database cannot be removed because it is referred to by a document.
BTS_E_ENVELOPE_UNIQUE_ID | 0x122D | The envelope identifier must be a unique identifier.
BTS_E_ENVELOPE_UNIQUE_NAME | 0x122E | The envelope name must be a unique name.
BTS_E_ENVELOPE_FOREIGN_SHAREID | 0x1230 | The XML Share table in the SQL Server database cannot be removed because it is referred to by an envelope.
BTS_E_CONTROLNUMBER_UNIQUE_ID | 0x1231 | The control-number identifier must be a unique identifier.
BTS_E_PORTGROUP_UNIQUE_ID | 0x1232 | The distribution list identifier must be a unique identifier.
BTS_E_PORTGROUP_UNIQUE_NAME | 0x1233 | The distribution list name must be a unique name.
BTS_E_MISSING_VALUE | 0x1235 | The identifier value property must have a value.
BTS_E_MISSING_SRCORGID | 0x1236 | The Channel SourceOrganization property must have a value.
BTS_E_APPLICATION_UNIQUE_ID | 0x1237 | The application identifier must be a unique identifier.
BTS_E_APPLICATION_FOREIGN_OWNERID | 0x1238 | The organization cannot be removed because it is referred to by an application.
BTS_E_APPLICATION_UNIQUE_NAME | 0x1239 | For applications within this organization, the application name must be a unique name.
BTS_E_CHANNEL_UNIQUE_ID | 0x123A | The channel identifier must be a unique identifier.
BTS_E_CHANNEL_UNIQUE_NAME | 0x123B | The channel name must be a unique name.
BTS_E_CHANNEL_FOREIGN_INPDOCID | 0x123D | The inbound document cannot be removed because it is used by a channel.
BTS_E_CHANNEL_FOREIGN_OUTDOCID | 0x123E | The output document cannot be removed because it is used by a channel.
BTS_E_CHANNEL_FOREIGN_PORTGROUPID | 0x123F | The distribution list cannot be removed because it is used by a channel.
BTS_E_CHANNEL_FOREIGN_SRCORGID | 0x1240 | The source organization cannot be removed because it is used by a channel.
BTS_E_ENVELOPE_INVALIDFORMAT | 0x1241 | The only valid envelope-format strings are: Custom, Custom XML, EDIFACT, Flatfile, X12, and Reliable. The previously specified format will remain unchanged.
BTS_E_CHANNEL_FOREIGN_CONTROLNUMID | 0x1242 | The control number cannot be removed because it is used by an channel.
BTS_E_PORT_UNIQUE_ID | 0x1243 | The messaging port identifier must be a unique identifier.
BTS_E_PORT_UNIQUE_NAME | 0x1244 | The messaging port name must be a unique name.
BTS_E_CHANNEL_FOREIGN_SRCAPPID | 0x1247 | The source application cannot be removed because it is used by a channel.
BTS_E_PORT_FOREIGN_DSTORGID | 0x1248 | The destination organization cannot be removed because it is used by a messaging port.
BTS_E_PORT_FOREIGN_DSTALIASID | 0x1249 | The destination identifier cannot be removed because it is used by a messaging port.
BTS_E_PORT_FOREIGN_ENVID | 0x124A | The envelope cannot be removed because it is used by a messaging port.
BTS_E_CHANNEL_FOREIGN_SRCALIASID | 0x124B | The source identifier cannot be removed because it is used by a channel.
BTS_E_PORT_FOREIGN_DSTAPPID | 0x124C | The destination application cannot be removed because it is used by a messaging port.
BTS_E_PORT_FOREIGN_CONTROLNUMID | 0x124D | The control number cannot be removed because it is used by a messaging port.
BTS_E_DOCUMENT_MISSING_REFERENCE | 0x124E | The Reference property must have a value if the TrackingFields or PropertySet properties are specified.
BTS_E_DOCUMENT_REFERENCE_CANT_BE_CHANGED | 0x124F | A document reference cannot be modified if it is referred to by a channel.
BTS_E_PORTGROUP_NOTOPENGRP | 0x1251 | Messaging ports that are set to an open destination or set to an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW) cannot be used in distribution lists.
BTS_E_PORTGROUP_DUPLICATEPORT | 0x1252 | A duplicate messaging port cannot be added to the distribution list.
BTS_E_OUTPUTCONFIG_UNIQUE_ID | 0x1255 | The output configuration identifier must be a unique identifier.
BTS_E_OUTPUTCONFIG_FOREIGN_PORTID | 0x1256 | The messaging port cannot be removed because it is used by a channel.
BTS_E_OUTPUTCONFIG_FOREIGN_CHANNELID | 0x1257 | The channel cannot be removed because it is used by a messaging port.
BTS_E_PORT_LOOPBACK_RELIABLE | 0x125F | A messaging port with the transport type Loopback cannot be associated with an envelope that uses the Reliable format.
BTS_E_ALIAS_RESERVEDWORD | 0x1262 | Group is a reserved word for qualifiers and cannot be used as the qualifier for an identifier.
BTS_E_DOCUMENT_NEEDMAPREF | 0x1268 | A map reference is required to transform the inbound document to the outbound document if the document specifications are different.
BTS_E_PORT_DESTORGNOTSPECIFIED | 0x126C | This messaging port must have a destination organization specified.
BTS_E_PORT_MISSING_PRITRANSTYPE | 0x126D | You must specify a primary transport type for this messaging port. The primary transport cannot be blank, and it cannot be an open destination.
BTS_E_PORT_MISSING_PRITRANSADDRESS | 0x126E | This messaging port must have a primary transport address specified.
BTS_E_PORT_INVALID_SECTRANSTYPE | 0x126F | The secondary transport type cannot be set to Open, Loopback, or to BizTalk Orchestration Activation.
BTS_E_PORT_MISSING_SECTRANSADDRESS | 0x1270 | The secondary transport address is missing, although the transport type has been defined.
BTS_E_PORT_INVALID_ORG | 0x1271 | The organization specified in this messaging port does not exist.
BTS_E_PORT_INVALID_ALIAS | 0x1272 | The identifier specified for the organization in this messaging port either does not exist or it does not belong to the organization.
BTS_E_PORT_INVALID_APPLICATION | 0x1273 | The application specified for the organization in this messaging port either does not exist or it does not belong to the organization.
BTS_E_PORT_INVALID_ENVELOPE | 0x1274 | The envelope specified in this messaging port does not exist.
BTS_E_PORT_OPEN_DESTORG_SPECIFIED | 0x127C | An open-destination messaging port cannot have a destination organization specified.
BTS_E_PORT_OPEN_DESTAPP_SPECIFIED | 0x127E | An open-destination messaging port cannot have a destination application specified.
BTS_E_PORT_OPEN_PRITRANSTYPEOPEN | 0x127F | An open-destination messaging port must specify a primary transport type as an open destination.
BTS_E_PORT_OPEN_PRITRANSADDRESS | 0x1280 | An open-destination messaging port cannot specify a primary transport address.
BTS_E_PORT_OPEN_PRITRANSPARAMETER | 0x1281 | An open-destination messaging port cannot specify a primary transport parameter.
BTS_E_PORT_OPEN_SECTRANSTYPE | 0x1282 | An open-destination messaging port cannot specify the secondary transport type.
BTS_E_PORT_OPEN_SECTRANSADDRESS | 0x1283 | An open-destination messaging port cannot specify a secondary transport address.
BTS_E_PORT_OPEN_SECTRANSPARAMETER | 0x1284 | An open-destination messaging port cannot specify a secondary transport parameter.
BTS_E_PORT_OPEN_ENCRYPTIONTYPE | 0x1285 | An open-destination messaging port cannot specify an encryption type.
BTS_E_PORT_OPEN_ENCRYPTIONREF | 0x1286 | An open-destination messaging port cannot specify an encryption reference.
BTS_E_PORT_SIGNATTYPEANDREFERENCE | 0x1287 | The signature type is specified; however, the signature reference is missing.
BTS_E_PORT_ENCRYPTIONTYPEANDREFERENCE | 0x1288 | The encryption type is specified; however, the encryption reference is missing.
BTS_E_ALIAS_DEFAULT | 0x128A | One and only one default identifier is required and permitted at all times. The default identifier cannot be missing, nor can it be duplicated.
BTS_E_ALIAS_AUTO | 0x128B | The alias, which uses the name "Organization" and the qualifier "OrganizationName," is a system-created alias. You cannot remove this alias, create another alias that uses the same name and qualifier, or change any fields of this alias.
BTS_E_TRANSPORT_SYNTAXAPPINT | 0x128E | Either the syntax of this address is incorrect for the Application Integration Component transport type property, or the component is not registered, or else the component is not a valid AIC component.
BTS_E_TRANSPORT_SYNTAXFILE | 0x128F | The syntax of this address is incorrect for the File transport type.
BTS_E_TRANSPORT_SYNTAXHTTP | 0x1291 | The syntax of this address is incorrect for the HTTP transport type.
BTS_E_TRANSPORT_SYNTAXHTTPS | 0x1292 | The syntax of this address is incorrect for the HTTPS transport type.
BTS_E_TRANSPORT_SYNTAXSMTP | 0x1293 | The syntax of this address is incorrect for the SMTP transport type.
BTS_E_TRANSPORT_SYNTAXNONE | 0x1294 | You cannot specify a transport address or a parameter when the transport type is set to None, or when the source or destination are Open.
BTS_E_TRANSPORT_LOCALHOST | 0x1295 | The transport address cannot contain the word "localhost". Replace it with the computer name instead.
BTS_E_PORTGROUP_LASTPORT | 0x1296 | The messaging port cannot be removed if it is the last remaining messaging port in a distribution list.
BTS_E_TRANSPORT_MISSING_PRISMTPPARAMETER | 0x1298 | A primary transport parameter is required for the SMTP transport type.
BTS_E_TRANSPORT_MISSING_SECSMTPPARAMETER | 0x1299 | A secondary transport parameter is required for the SMTP transport type.
BTS_E_NAMEREQ | 0x129A | The Name property must always be at least one character long.
BTS_E_INVALIDTIMEFORMAT | 0x129B | The time format is not valid. Enter the time, in hours, in a 24-hour format (from 0 to 23 hours). You can enter only hours, not minutes or seconds.
BTS_E_TIMESTAMP | 0x129C | This object cannot be saved or removed because the timestamp has changed.
BTS_E_PORTGROUP_MISSING_PORT | 0x129D | A distribution list must contain at least one messaging port.
BTS_E_ORGANIZATION_REMOVEDEFAULT | 0x129E | The home organization cannot be removed.
BTS_E_PORT_SERVICEWINDOW_EQUAL | 0x129F | The start time (FromTime) and end time (ToTime) for the service window cannot be equal.
BTS_E_ENVELOPE_REFERENCENOTALLOWED | 0x12A2 | The reference property cannot be set for this envelope format.
BTS_E_ENVELOPE_REFERRED | 0x12A3 | This envelope cannot be removed because it is used in a messaging port or channel.
BTS_E_TRANSPORT_LOOPBACK_SECTYPECONFLICT | 0x12A4 | The secondary transport type cannot be specified for the messaging port if the primary transport type is set to Loopback.
BTS_E_TRANSPORT_LOOPBACK_SECADDRESSCONFLICT | 0x12A5 | The secondary transport address cannot be specified for the messaging port if the transport type is set to Loopback.
BTS_E_PORT_LOOPBACK_SERVICEWINDOW | 0x12A6 | The service window cannot be specified for the messaging port if the transport type is set to Loopback.
BTS_E_PORT_OPEN_DESTALIAS_SPECIFIED | 0x12A7 | An open-destination messaging port cannot have a destination identifier specified.
BTS_E_PORT_OPEN_SERVICEWINDOW | 0x12A8 | The service window cannot be specified for the messaging port if the messaging port is an open-destination messaging port.
BTS_E_PORT_SERVICEWINDOWTIMES | 0x12AA | To use a service window, you must set both the From and To times or else, do not set either time.
BTS_E_TRANSPORT_LOOPBACK_PRIADDRESSCONFLICT | 0x12AC | A primary transport address cannot be specified for the messaging port if the transport type is Loopback.
BTS_E_PORT_ORGCHANGE | 0x12AD | The destination-organization identifier cannot be changed after it is created.
BTS_E_PORT_OPENNESSCHANGE | 0x12AE | The Openness property cannot be changed after it is created.
BTS_E_PORT_SIGNATURE_CHANNEL_CERTREF | 0x12AF | The signature-certification reference for a channel does not match the signature type for the port.
BTS_E_PORT_SIGNATURE_CHANNEL_OPEN | 0x12B0 | A messaging port that contains a signature type cannot be connected to an open-source channel. Also, a messaging port that is already connected to an open-source channel cannot have a signature type assigned to it.
BTS_E_CHANNEL_OPEN_SRCORG | 0x12B1 | An open-source channel cannot specify a source organization.
BTS_E_PORTGROUP_LOOPBACKPORT | 0x12B2 | A messaging port that uses the Loopback transport type cannot be added to a distribution list. Also, the transport type of a messaging port that is already included in a distribution list cannot be changed to Loopback.
BTS_E_CHANNEL_OPEN_SRCALIAS | 0x12B3 | An open-source channel cannot have a source identifier specified.
BTS_E_CHANNEL_OPEN_SRCAPP | 0x12B4 | An open-source channel cannot specify a source application.
BTS_E_CHANNEL_PORTORPORTGROUP | 0x12B5 | Either a messaging port or a distribution list, but not both, must be specified in a channel.
BTS_E_CHANNEL_MISSING_DOCUMENT | 0x12B6 | Both input and output documents are needed in a channel.
BTS_E_CHANNEL_INVALIDTYPE | 0x12B7 | A channel cannot be set to an open destination or set to an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW).
BTS_E_CHANNEL_MISSING_OUTDOCREFERENCE | 0x12B8 | If the inbound document definition for a channel has a reference to a specification, the outbound document definition must also have a reference to a specification.
BTS_E_CHANNEL_TRACKFIELDSCANTBESET | 0x12B9 | If the inbound document definition for a channel does not have a reference to a specification, the tracking fields cannot be set.
BTS_E_CHANNEL_EXPRESSIONCANTBESET | 0x12BA | If the inbound document definition for a channel does not have a reference to a specification, the channel-filtering expressions cannot be set.
BTS_E_CHANNEL_MAPREFCANTBESET | 0x12BB | If the inbound document definition for a channel does not have a reference to a specification then a reference to a map cannot be set.
BTS_E_CHANNEL_NOTSAME_INPDOC_OUTDOC | 0x12BC | If the inbound document definition for a channel does not have a reference to a specification then the outbound document handle should be the same of inbound document handle.
BTS_E_CHANNEL_OPEN_RECEIPTCONFLICT | 0x12BD | Channels that are set from an open source or set from an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW) cannot be receipt channels.
BTS_E_CHANNEL_RECEIPT_RECEIPTTIMEOUT | 0x12BE | The Expect Receipt Timeout property cannot be set on a receipt channel.
BTS_E_CHANNEL_RECEIPT_CANTSETRECEIPTCHANNEL | 0x12BF | An identifier cannot be set on a receipt channel.
BTS_E_CHANNEL_RECEIPT_CONFLICT | 0x12C0 | In a receipt channel, the source specification from the original channel must be used as the destination specification, and the destination specification from the original channel must be used as the source specification.
BTS_E_CHANNEL_SRCORGDEFAULT | 0x12C1 | If the channel is set from an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW), the source organization must be the home organization.
BTS_E_CHANNEL_PORT_BOTHOPEN | 0x12C2 | Both the channel and messaging port cannot be set to Open.
BTS_E_CHANNEL_RECEIPT_INVALID | 0x12C3 | The Receipt Channel and Expect Receipt Timeout properties cannot be set for an open-source channel. These properties also cannot be set if the messaging port is set to an open destination, set to an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW), or if the messaging port uses the Loopback transport type.
BTS_E_CHANNEL_RECEIPTMATCHNOTFOUND | 0x12C4 | The corresponding receipt channel for this channel could not be found.
BTS_E_CHANNEL_RECEIPT_OPENPORT | 0x12C5 | A receipt channel can be connected only to messaging ports that are not open messaging ports.
BTS_E_CHANNEL_RECEIPT_LOOPBACKPORT | 0x12C6 | A receipt channel cannot be connected to a messaging port that uses the Loopback transport type. Also, the transport type of a messaging port that is already connected to a receipt channel cannot be changed to Loopback.
BTS_E_CHANNEL_CANNOTUPDATE | 0x12C8 | After a channel is created, the following properties cannot be changed: source organization, openness designation, messaging port, distribution list, and receipt channel designation.
BTS_E_PORT_INVALIDOPENNESS | 0x12C9 | A messaging port cannot be set to an open source; nor can it be set from an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_FROMWORKFLOW).
BTS_E_CHANNEL_CONTROLNUMBER_ENVELOPEFORMATMISMATCH | 0x12CA | If the envelope format for the messaging port is X12 or EDIFACT, the control-number value on the channel must be set.
BTS_E_PORT_ENVELOPE_SERIALIZERCLSID | 0x12CB | If the envelope format for the messaging port is set to Custom, a class identifier (CLSID) for the serializer component must be specified.
BTS_E_CHANNEL_AIC_TRANSPORTCLSID | 0x12CD | If the transport type associated with the channel is set to Application Integration Component, a class identifier (CLSID) must be specified for the primary transport.
BTS_E_CHANNEL_RECEIPT_PORTGROUP | 0x12CE | If a channel is connected to a distribution list, a receipt channel cannot be specified.
BTS_E_COMPONENTREQUIRES2AGGREGATEFTM | 0x12CF | To be a valid object in the BizTalk Object Model, this custom component must aggregate the free-threaded marshaler.
BTS_E_CERTREFNOTFOUND | 0x12D1 | Either the certificate reference could not be found in MY or BIZTALK stores or it is not valid.
BTS_E_NODOC | 0x12D2 | The Document Definition has been removed from the database. Avoid deleting objects when documents might exist in the queues which reference these objects.
BTS_E_NOENV | 0x12D3 | The envelope has been removed from the database. Avoid deleting objects when documents might exist in the queues which reference these objects.
BTS_E_NOCHANNEL | 0x12D4 | The channel has been removed from the database. Avoid deleting objects when documents might exist in the queues which reference these objects.
BTS_E_INVALIDREFERENCE | 0x12D5 | Either the WebDAV repository reference does not contain a valid HTTP address or it contains the text "localhost." Please provide either a valid HTTP address or replace the text "localhost" with the actual computer name.
BTS_E_CANNOTCONTAINSUBOBJECTS | 0x12D6 | The property set and delimiter objects cannot contain any subobjects.
BTS_E_INVALIDTRACKFIELDS | 0x12D7 | The "x_custom_search" field in the tracking field dictionary must be a simple list.
BTS_E_CHANNEL_INVALID_ORG | 0x12D8 | The organization specified in this channel does not exist.
BTS_E_CHANNEL_INVALID_ALIAS | 0x12D9 | The identifier specified for the organization in this channel either does not exist or it does not belong to the organization.
BTS_E_CHANNEL_INVALID_APPLICATION | 0x12DA | The application specified for the organization in this channel either does not exist or it does not belong to the organization.
BTS_E_CHANNEL_INVALID_INPDOCID | 0x12DB | The input document specified in this channel does not exist.
BTS_E_CHANNEL_INVALID_OUTDOCID | 0x12DC | The output document specified in this channel does not exist.
BTS_E_CHANNEL_INVALID_PORTGROUP | 0x12DD | The distribution list specified in this channel does not exist.
BTS_E_OBJECT_NOT_XMLSERILIZABLE | 0x12DE | The given dictionary or simplelist object must implement IPersistXML methods.
BTS_E_CHANNEL_INVALID_PORT | 0x12E0 | At least one messaging port that is referenced in this channel either does not exist or it is not associated with this channel.
BTS_E_CHANNEL_RECEIPT_VERSIGN_DECRYPT | 0x12E1 | The Verify Signature or Decrypt Encryption properties cannot be set on a receipt channel.
BTS_E_INVALID_REQUEST_CHANNEL | 0x12E2 | A channel that is connected to a distribution list cannot be used as a request channel.
BTS_E_DESTINATION_NOT_FOUND | 0x12E3 | The destination URL is not specified, and the messaging port is an open destination. Either the destination URL or a destination for the messaging port must be specified.
BTS_E_DESTINATION_CONFLICT | 0x12E4 | Both a destination URL and a destination for the messaging port cannot be specified. Specify only one of these properties.
BTS_E_ASYNC_TRANSPORT | 0x12E5 | The transport type for the request channel is not valid. Only the HTTP, HTTPS, and Application Integration Component transport types are valid for a request channel.
BTS_E_INVALID_RESPONSE_CHANNEL | 0x12E6 | The response channel can be connected only to a messaging port with a transport type set to Loopback.
BTS_E_INVALID_VERSION | 0x12E7 | The database version is incompatible with the installed version of the server. Try running setup again.
BTS_E_INVALID_SCHEMA | 0x12E8 | The document or envelope specification is not valid. Open the specification in BizTalk Editor, and then on the Tools menu, click Validate Specification. Resolve any warnings to ensure that the specification is valid.
BTS_E_CHANNEL_RECEIPTCHANNEL_PORTGROUP | 0x12E9 | A receipt channel cannot be connected to a distribution list.
BTS_E_TRANSPORT_ORCHESTRATION_OPENNESS | 0x12EA | A messaging port that uses the BizTalk Orchestration Activation transport type must have the Openness Type property set to an XLANG schedule (BIZTALK_OPENNESS_TYPE_EX_TOWORKFLOW).
BTS_E_TRANSPORT_ORCHESTRATION_ADDRESSPARAMETER | 0x12EB | Both a primary address and a parameter are required for a messaging port that uses a BizTalk Orchestration Activation transport type.
BTS_E_ORCHESTRATION_INVALIDORG | 0x12EC | A messaging port that uses a BizTalk Orchestration Activation transport type must have the home organization set as the destination organization.
BTS_E_INVALID_FILTEREXPRESSION | 0x12ED | The channel filtering expression is not valid. Make sure that the node-path expression is valid.
BTS_E_MULTIPLEDOCDEFSFORPROPSET | 0x12EE | Multiple document definitions were found for the given property set. Only a single document definition for a given property set is expected.
BTS_E_INVALID_PROPSET | 0x12EF | The PropertySet cannot contain non-string element values.
BTS_E_DBSCHEMA_MISMATCH | 0x1300 | The existing Database Schema is not compatible with the current version of the product. You must delete the existing database.
BTS_E_UNEXPECTED_INSTALL | 0x1301 | The existing Database Schema is newer than the current version that is installed. Setup will rollback the changes.
CIS_E_DOCSCHEMA_ATTRIB_MISSING | 0x1400 | The "%3" attribute is missing in the "%4" element. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_ATTRIB_VALUE | 0x1401 | The "%3" attribute value "%4" is not valid. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_EMPTY_ELEMENT | 0x1402 | The "%3" element cannot be empty. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_CHILD_ELEMENT | 0x1403 | The "%3" element cannot be a child of the "%4" element. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_MULTIPLE_INFO | 0x1404 | Only one record description or one field description is allowed for each element declaration. One of the descriptions must be removed. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_FIELD_DECL | 0x1405 | The root node cannot contain a field. The root node of the document must contain a record. Verify that the root node in your document is declared as a record. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_LEN_DECL | 0x1406 | The minimum length value must be no greater than the maximum length value. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_POSLEN_DECL | 0x1407 | The value of the start position must be no greater than the value of the end position. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_NO_INFO_YET | 0x1408 | A field description or record description must be specified before references to other elements. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_SCHEMATYPE_XML | 0x1409 | Only non-XML document specifications are allowed for this format. The schema_type attribute has the value "xml". Verify that the specification selected is a non-XML specification. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_NO_INFO | 0x140A | No record information or field information was found in the "%3" element. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_ATTRIB | 0x140B | The "%3" attribute is not allowed in the "%4" element. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_MISSING_ELEM_DECL | 0x140C | There is no element with the name "%1" in the document specification.
CIS_E_DOCSCHEMA_MISSING_ATTR_DECL | 0x140D | There is no attribute with the name "%1" in the document specification.
CIS_E_DOCSCHEMA_INVALID_POSITIONAL_DECL | 0x140E | The "%1" record cannot be a child of the "%2" positional record. Only fields can be children of positional records.
CIS_E_DOCSCHEMA_INVALID_RECORD_CHILDREN | 0x140F | The children of the "%1" delimited record must either be all records or all fields. Records with no tag identifier cannot have mixed records and fields as children.
CIS_E_DOCSCHEMA_NO_RECORD_CHILDREN | 0x1410 | The "%1" delimited record must have at least one child. Records with no tag identifier must have at least one child, or else the record cannot be found in a non-XML format. Either add a child to the record, give the record a tag identifier, or remove the record from the specification.
CIS_E_DOCSCHEMA_MISSING_RECORD_TAG | 0x1411 | The "%1" delimited record is marked to repeat but it does not have a tag identifier. Only the last record in a document specification is allowed to have this property. If this record appears only once in the document, then mark it as a single occurrence. Otherwise, give the record a tag identifier that tells the server where to look for the next record in the specification.
CIS_E_DOCSCHEMA_NO_ROOT_ELEMENT | 0x1412 | The root-node name "%3" was not found in the specification. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_ROOT_ELEMENT | 0x1413 | The "%3" element cannot be the root node of this document. Only <Schema> is allowed. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_EMPTY_ATTRIBUTE | 0x1414 | The "%3" attribute in the "%4" element cannot be empty. Either specify a nonempty value or remove the attribute. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_INVALID_REFERENCE | 0x1415 | The "%1" record has an illegal cyclic path through the "%2" record. The only cyclic reference allowed for a record is if the record has a tag identifier that allows the system to terminate the search. Either remove the cyclic reference or add an appropriate tag identifier to the document specification.
CIS_E_DOCSCHEMA_LOADFAILED | 0x1416 | The specification failed to load. See the following messages for details.
CIS_E_DOCSCHEMA_MISSING_NS | 0x1417 | Valid BizTalk Server specifications for non-XML documents must have the namespace declarations of "urn:schemas-microsoft-com:BizTalkServer", "urn:schemas-microsoft-com:datatypes", and "urn:schemas-microsoft-com:xml-data" in the root node of the specification.
CIS_E_DOCSCHEMA_INVALID_SCHEMA_USAGE | 0x1418 | The specification referenced in the "%1" document is not compatible with the "%2" format. Select a specification that is compatible with this format, or if this is a valid specification for the defined format, assign "%2" to the "standard" property on this specification.
CIS_E_DOCSCHEMA_MISSING_POSLEN_DECL | 0x1419 | The "%3" field is missing a start and end position, and is referenced in the "%4" positional record. Specify valid start and end positions for this field. Line: %1, Pos: %2.
CIS_E_DOCSCHEMA_DUPLICATE_NAMESPACE | 0x141A | The duplicate namespace declaration "%3" has been found. Please remove the duplicate reference to same namespace. Line: %1, Pos: %2.
CIS_E_PARSER_EOF | 0x1430 | The end of the file was reached prematurely.
CIS_E_PARSER_MISSING_TAG | 0x1431 | The required "%1" record was not found in the inbound document.
CIS_E_PARSER_MISSING_FIELD | 0x1432 | The required field "%1" in the "%2" record was not found in the inbound document.
CIS_E_PARSER_FAILURE | 0x1433 | The parser failed to convert the document due to processing errors. See the following messages for details.
CIS_E_PARSER_INVALIDDATA | 0x1434 | The parser cannot match the current position of the data with the specification. Verify that the version of this specification is consistent with the version of the data and that the root parsing tags match.
CIS_E_PARSER_NO_DATA | 0x1435 | There is no data that can be parsed on the dictionary. Verify that either the "working_data" field or the "file_path" field contains nonempty data.
CIS_E_PARSER_INVALID_ENVNAME | 0x1436 | The envelope name "%1" does not reference a valid envelope for the BizTalk Server parser. Either the envelope name does not exist or there is an envelope specification attached that is not valid.
CIS_E_PARSER_NO_COMPONENTS_FOUND | 0x1439 | No parser component recognizes the data. This might be caused by an interchange specification that is missing or not valid, or it might be caused by data that is not valid. Verify that both the interchange specification (if one is specified) and the data match.
CIS_E_PARSER_COMPONENT_FAILED | 0x1440 | While trying to process document #%4 during submission "%1", the parser component named "%2" failed on the method "%3" with the error code "%5". Possible causes are: the component found unexpected data in the incoming stream; a document specification could not be found given the data; or an internal component failure occurred. If this problem continues, remove this component from the valid list of parser components or contact your system administrator.
CIS_E_PARSER_DOCUMENT_FAILED | 0x1441 | Document #%4 within submission "%1" was returned as a document that was not valid from the parser component named "%2". The most frequent cause is a document specification that is not valid or else the component was unable to determine the necessary routing fields. Verify that the proper specification is defined for this data.
CIS_E_PARSER_INVALID_DATETIME | 0x1442 | The "%1" date or time format for the tag "%3" does not match the format of the "%2" data extracted from the incoming data.
CIS_E_PARSER_INVALID_COMPONENT | 0x1443 | Within submission "%1", the parser component named "%2" could not be loaded. Verify that this component can be run in a stand-alone executable and that the server has sufficient permissions to start it.
CIS_W_PARSER_SKIPPED_COMPONENT | 0x1444 | The parser was unable to probe the specified component. This component will be skipped.
CIS_E_PARSER_UNUSEABLE_DOCNAME | 0x1445 | The parser cannot use the document "%1" as it has no specification. Please attach a specification to this document or specify a different one.
CIS_E_PARSER_CONTROL_NUMBER_MISMATCH | 0x1446 | The control number of segment "%1" (%2) does not match that of segment "%3" (%4).
CIS_E_PARSER_DOCCOUNT_INCORRECT | 0x1447 | The document or segment count contained in tag "%1" (%2) does not match the number of documents or segments processed (%3).
CIS_E_PARSER_X12_ISA_PARSE_FAILED | 0x1448 | The parser cannot parse the ISA section of the X12 document. This segment is fixed-width; if fields in this segment do not have correct length, the parsing will fail because the delimiters are picked up from the wrong offsets.
CIS_E_PARSER_MIN_LENGTH | 0x1449 | The data contains a field value ("%1") that doesn't meet minimum length requirement for tag "%2" (minimum length is %3).
CIS_E_PARSER_MAX_LENGTH | 0x144A | The data contains a field value ("%1") that doesn't meet maximum length requirement for tag "%2" (maximum length is %3).
CIS_E_PARSER_NO_DATA_CONSUMED | 0x144B | No data was read by the parser. Make sure that the code page is set correctly for the data. If the data is UNICODE, make sure that there is no byte order mark (0xFFFE or 0xFEFF) appears at the beginning of the file.
CIS_E_PARSER_UNSUPPORTED_EDIFACT_SYNTAX | 0x144C | EDIFACT documents with the "UNOX" or the "UNOY" syntax identifier are not supported.
CIS_E_PARSER_DATA_REMAINING | 0x144D | Additional data in the document instance was not parsed. Make sure that the document instance you want to validate contains only one document.
CIS_E_PARSER_MISSING_DELIMITER | 0x144E | While parsing record "%1", the parser cannot find the required delimiter: "%2" (%3).
CIS_E_PARSER_MISSING_LEADING_DELIMITER | 0x144F | While parsing record "%1", the parser cannot find the required leading delimiter: "%2" (%3).
CIS_E_PARSER_MISSING_TRAILING_DELIMITER | 0x1450 | While parsing record "%1", the parser cannot find the required trailing delimiter: "%2" (%3).
CIS_E_VALIDATE_GROUP_RULE | 0x1451 | In record "%1", if any of the following fields exist, then all must exist: %2
CIS_E_VALIDATE_GROUP_ALL | 0x1452 | In record "%1", all of the following fields must exist: %2
CIS_E_VALIDATE_GROUP_ONE | 0x1453 | In record "%1", only one of the following fields can exist: %2
CIS_E_PARSER_INVALID_WRAP_CHAR_FOUND | 0x1454 | While parsing record "%1", the parser found an occurrence of a wrap character, "%2", that is not valid.
CIS_E_VALIDATE_GROUP_ANY | 0x1455 | In record "%1", one or more of the following fields must exist: %2
CIS_E_PARSER_EXTRA_DELIMITER | 0x1456 | While parsing record "%1", the parser found the following extra delimiter: "%2".
BTS_E_DOCUMENT_HAS_INVALID_MANIFEST | 0x1457 | Error parsing the manifest.
CIS_E_ADMIN_CACHE_PARSERS | 0x1504 | The latest modification date from the administration parser table could not be loaded.
CIS_E_ADMIN_INIT_CACHE | 0x1505 | The configuration data in the global cache could not be initialized.
CIS_E_ADMIN_RELOAD_CACHE | 0x1506 | The configuration data from the database could not be reloaded.
CIS_E_ADMIN_PARSER_GETCLSID | 0x1507 | The class identifiers (CLSIDs) of the parser records could not be loaded.
CIS_E_ADMIN_CACHE_OBJECTNOTCREATED | 0x1509 | The administration cache cannot be created.
CIS_E_ADMIN_CACHE_INITIALLOAD | 0x150A | The configuration cache data from the database could not be loaded.
CIS_E_ADMIN_ADD_SERVER_ACCESS_DENIED | 0x150B | Server "%1" cannot be added because access to the "%2" is denied.
CIS_E_ADMIN_ADD_SERVER_NO_SERVICE | 0x150C | Server "%1" cannot be added because BizTalk Server is not installed on the computer.
CIS_E_ADMIN_DELETE_SERVER_NO_ACCESS | 0x150D | The "%1" server cannot be deleted because access to the "%2" service is denied and the service cannot be stopped.
CIS_E_ADMIN_DELETE_GROUP_SERVER_RUNNING | 0x150E | This server group cannot be deleted because the "%1" server is still running.
CIS_E_ADMIN_DELETE_GROUP_SERVER_ACCESS_DENIED | 0x150F | This server group cannot be deleted because access to the "%1" service on "%2" server is denied.
CIS_E_ADMIN_NOGROUP | 0x1512 | The specified administration group does not exist.
CIS_E_ADMIN_NOSERVER | 0x1513 | The specified administration server does not exist.
CIS_E_ADMIN_NORECEIVESERVICE | 0x1514 | The specified administration receive function does not exist in the database.
CIS_E_ADMIN_UNEXPECTED_REMOVE_RECEIVESERVICE | 0x1515 | An unexpected error occurred while trying to remove the "%1" receive function from the database.
CIS_E_ADMIN_UNEXPECTED_REMOVE_GROUP | 0x1516 | An unexpected error occurred while trying to remove the "%1" group from the database.
CIS_E_ADMIN_UNEXPECTED_REMOVE_SERVER | 0x1517 | An unexpected error occurred while trying to remove the "%1" server from the database.
CIS_E_ADMIN_NOTIMESTAMPS | 0x151A | The specified administration timestamps object does not exist in the database.
CIS_E_ADMIN_REFRESH_THREAD_ERROR | 0x151B | The configuration refresh thread encountered an error while loading the configuration data.
CIS_E_ADMIN_REFRESH_THREAD_EXIT | 0x151C | The configuration refresh thread cannot load the configuration data because of a previous error.
CIS_E_ADMIN_RECSVC_GENERAL | 0x151D | The configuration refresh thread cannot set up one or more receive functions. This might be because SQL Server is not started.
CIS_E_ADMIN_CREATE_GROUP | 0x1529 | The server group cannot be created because "%1".
CIS_E_ADMIN_LOAD_GROUP_PROPS | 0x152A | The group properties cannot be loaded because "%1".
CIS_E_ADMIN_SAVE_GROUP_PROPS | 0x152B | The group properties cannot be saved because "%1".
CIS_E_ADMIN_REMOVE_GROUP | 0x152C | The server group cannot be removed from the database because "%1".
CIS_E_ADMIN_GETALLADMINGROUPS | 0x152D | All server groups cannot be retrieved from the database.
CIS_E_ADMIN_GETSERVERS | 0x152E | All servers for the "%1" server group cannot be retrieved from the database because "%2".
CIS_E_ADMIN_GETRECEIVESERVICES | 0x152F | All receive functions for the "%1" group cannot be retrieved from database because "%2".
CIS_E_ADMIN_GETPARSERS_IN_GROUP | 0x1531 | All parsers for the "%1" server group cannot be retrieved from the database because "%2".
CIS_E_ADMIN_GETLOCALSMTPHOST | 0x1538 | The local SMTP host cannot be retrieved because "%1".
CIS_E_ADMIN_CREATE_SERVER | 0x1539 | The server cannot be created because "%1".
CIS_E_ADMIN_LOAD_SERVER_PROPS | 0x153A | The server properties cannot be loaded because "%1".
CIS_E_ADMIN_SAVE_SERVER_PROPS | 0x153B | The server properties cannot be saved because "%1".
CIS_E_ADMIN_REMOVE_SERVER | 0x153C | The server cannot be removed from the database because "%1".
CIS_E_ADMIN_GETALLADMINSERVRES | 0x153D | All servers cannot be retrieved from the database.
CIS_E_ADMIN_GETSERVERBYNAME | 0x153E | The server properties for "%1" cannot be retrieved because "%2".
CIS_E_ADMIN_DECRYPT_PASSWORD | 0x1540 | The "%1" property cannot be retrieved.
CIS_E_ADMIN_EXEC_COMMMAND_ON_PARSER | 0x154F | The SQL command "%1" on the parser database table cannot be executed because "%2".
CIS_E_ADMIN_PREPOROCESSOR_NOT_SUPPORTED_BY_HTTP_RF | 0x155C | The "%1" property is not supported for the HTTP receive function in Submit to File mode.
CIS_E_ADMIN_CREATE_RECEIVESERVICE | 0x155D | The receive function cannot be created because "%1".
CIS_E_ADMIN_LOAD_RECEIVESERVICE_PROPS | 0x155E | The receive function properties cannot be loaded because "%1".
CIS_E_ADMIN_SAVE_RECEIVESERVICE_PROPS | 0x155F | The receive function properties cannot be saved because "%1".
CIS_E_ADMIN_REMOVE_RECEIVESERVICE | 0x1560 | The receive function cannot be removed from the database because "%1".
CIS_E_ADMIN_GETALLRECEIVESERVICES | 0x1561 | All receive functions cannot be retrieved from the database because "%1".
CIS_E_ADMIN_GETALLRECEIVESERVICESINSERVER | 0x1562 | All receive functions cannot be retrieved for the "%1" server because "%2".
CIS_E_ADMIN_LOAD_TIMESTAMPS | 0x1563 | All timestamps cannot be retrieved from the database because "%1".
CIS_E_ADMIN_GETSQCONNECT | 0x1570 | The Shared Queue database connection string cannot be retrieved from the database.
CIS_E_ADMIN_GETCOMPUTERNAME | 0x1571 | The name of the local computer cannot be retrieved. Internally, BizTalk Server is using "localhost" as the computer name.
CIS_E_ADMIN_MIN_CONSTRAINT | 0x1573 | The size of the "%1" property is less than the minimum required length for "%2".
CIS_E_ADMIN_MAX_CONSTRAINT | 0x1574 | The size of the "%1" property is greater than the maximum length allowed for "%2".
CIS_E_ADMIN_GET_MGMTDB_CONNECT_PROPS | 0x1575 | The BizTalk Messaging Management database properties cannot be retrieved.
CIS_E_ADMIN_KEY_EMPTY | 0x1576 | The key to the database table, property "%1", is empty.
CIS_E_ADMIN_COCREATE_IN_CREATE | 0x1577 | An instance of the "%1" object could not be created while creating a new "%2" object.
CIS_E_ADMIN_ADO_OPEN_CONNECTSTRING | 0x1578 | The connection to the BizTalk Messaging Management database could not be opened.
CIS_E_ADMIN_COCREATE_IN_LOAD | 0x1579 | An instance of the "%1" object could not be created while loading the "%2" properties.
CIS_E_ADMIN_COCREATE_IN_SAVE | 0x1580 | An instance of the "%1" object could not be created while saving the "%2" properties.
CIS_E_ADMIN_COCREATE_IN_REMOVE | 0x1581 | An instance of the "%1" object could not be created while trying to remove the "%2" object.
CIS_E_ADMIN_COCREATE_IN_GETALL | 0x1582 | An instance of the "%1" object could not be created while trying to get all instances of "%2".
CIS_E_ADMIN_COCREATE_IN_GETALL_INSERVER | 0x1583 | An instance of the "%1" object could not be created while trying to get all instances of the "%2" object in the "%3" server.
CIS_E_ADMIN_GET_PROP | 0x1584 | The "%1" property cannot be retrieved.
CIS_E_ADMIN_CLOSE_ADO_CONNECTION | 0x1585 | The ADO connection cannot be closed.
CIS_E_ADMIN_CLOSE_ADO_RECORDSET | 0x1586 | The ADO record set cannot be retrieved.
CIS_E_ADMIN_ENCRYPT_PASSWORD | 0x1587 | The "%1" property cannot be processed.
CIS_E_ADMIN_COCREATE_IN_GETALLNAMES | 0x1588 | An instance of the "%1" object could not be created while trying to get the names of all the "%2" object instances.
CIS_E_ADMIN_COCREATE_IN_GETOTHERS_OF_GROUP | 0x1589 | An instance of the "%1" object could not be created while trying to get all instance of the "%2" object in the "%3" group.
CIS_E_ADMIN_COCREATE_IN_GET_SMTPHOST | 0x158A | An instance of the "%1" object could not be created while trying to get "%2" for the local server.
CIS_E_ADMIN_COCREATE_IN_GET_SQ_CONNECTSTRING | 0x158B | An instance of the "%1" object could not be created while trying to get the Shared Queue parameters of "%2" in order to connect to the database.
CIS_E_ADMIN_COCREATE_SERVER_BYNAME | 0x158C | An instance of the "%1" object could not be created while trying to get the properties of the "%2" server instance of the "%3" class.
CIS_E_ADMIN_GETSQCONNECT_IN_OPEN | 0x158D | The Shared Queue database connection string could not be retrieved from the database because "%1".
CIS_E_ADMIN_COCREATE_EXEC_SQL_COMMAND_ON_PARSER | 0x158E | An instance of the "%1" object could not be created while trying to execute a SQL command on the "%2" database table.
CIS_E_ADMIN_COCREATE_PARSER_CLSIDS_IN_GROUP | 0x158F | An instance of the "%1" object could not be created while retrieving the class identifiers (CLSIDs) for the parsers that belong to the "%2" group.
CIS_E_ADMIN_INVALID_ARGUMENT | 0x1590 | An unexpected internal error occurred. An invalid "%1" argument was used when calling the "%2" method.
CIS_E_ADMIN_MAX_ENUM_CONSTRAINT | 0x1591 | The value of the "%1" property is greater than the maximum value allowed for "%2".
CIS_E_ADMIN_MIN_ENUM_CONSTRAINT | 0x1592 | The value of the "%1" property is smaller than the minimum value allowed for "%2".
CIS_E_ADMIN_CREATE_CHANGETYPE_TO_BSTR | 0x1593 | The type of the "%1" property could not be changed to a string.
CIS_E_ADMIN_CREATE_CHANGETYPE_TO_BOOL | 0x1594 | The type of the "%1" property could not be changed to Boolean.
CIS_E_ADMIN_COCREATE_IN_ENUMINSTANCES | 0x1595 | An instance of the "%1" object could not be created while enumerating instances of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_PUTINSTANCE | 0x1596 | An instance of the "%1" object could not be created while setting an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_GETOBJECT | 0x1597 | An instance of the "%1" object could not be created while getting an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_DELETEINSTANCE | 0x1598 | An instance of the "%1" object could not be created while deleting an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_LOADPROPS | 0x1599 | An instance of the "%1" object could not be created while loading properties for an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_LOADPARSERS | 0x159B | An instance of the "%1" object could not be created while loading parsers from a database for an instance the "%2" object.
CIS_E_ADMIN_COCREATE_IN_SETPARSERSFROM_REGISTRY | 0x159C | An instance of the "%1" object could not be created while setting parsers from the registry for an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_SETPARSERSFROM_CLIENT | 0x159D | An instance of the "%1" object could not be created while setting parsers from the client for an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_REFRESHPARSERLIST | 0x159E | An instance of the "%1" object could not be created while refreshing the parser list for an instance of the "%2" object.
CIS_E_ADMIN_COCREATE_IN_MOVETOSUSPENDED_Q | 0x159F | An instance of the "%1" object could not be created while moving an instance of "%2" to the Suspended queue.
CIS_E_ADMIN_COCREATE_IN_RESUBMIT | 0x15A0 | An instance of the "%1" object could not be created while resubmitting an instance of "%2".
CIS_E_ADMIN_COCREATE_IN_VIEWDOC | 0x15A2 | An instance of the "%1" object could not be created while viewing a document instance of "%2".
CIS_E_ADMIN_COCREATE_IN_VIEWERRORDESC | 0x15A3 | An instance of the "%1" object could not be created while viewing the error description of an instance of "%2".
CIS_E_ADMIN_COCREATE_IN_VIEWINTERCHANGE | 0x15A4 | An instance of the "%1" object could not be created while viewing the interchanges of an instance of "%2".
CIS_E_ADMIN_COCREATE_IN_FREEINTERCHANGES | 0x15A5 | An instance of the "%1" object could not be created while freeing the interchanges for an instance of a "%2".
CIS_E_ADMIN_COCREATE_IN_STARTSERVER | 0x15A6 | An instance of the "%1" object could not be created while starting the server for an instance of a "%2".
CIS_E_ADMIN_COCREATE_IN_STOPSERVER | 0x15A7 | An instance of the "%1" object could not be created while stopping the server for an instance of a "%2".
CIS_E_ADMIN_NO_DELETE_SERVER_IN_RECVSERVICE | 0x15A8 | The "%1" server cannot be deleted because it is the processing server for at least one receive function.
CIS_E_ADMIN_UPDATE_GROUP_SERVER_RUNNING | 0x15A9 | The server group properties cannot be changed because the "%1" server is still running.
CIS_E_ADMIN_UPDATE_GROUP_SERVER_ACCESS_DENIED | 0x15AA | The server group properties cannot be changed because access to the "%1" service on "%2" server is denied.
CIS_E_ADMIN_UPDATE_SERVER_SERVER_RUNNING | 0x15AC | The server properties cannot be changed because the "%1" server is still running.
CIS_E_ADMIN_UPDATE_SERVER_SERVER_ACCESS_DENIED | 0x15AD | The server properties cannot be changed because access to the "%1" service on "%2" server is denied.
CIS_E_ADMIN_UPDATE_READ_ONLY_PROP | 0x15AE | The "%1" property cannot be changed. It is a read only property.
CIS_E_ADMIN_DIFFERENT_ROOT | 0x15AF | The "%1" server may already belong to a different BizTalk Server installation.
CIS_E_ADMIN_NOT_RESUBMITABLE | 0x15B0 | This Suspended queue item cannot be submitted again.
CIS_E_ADMIN_DBCONNECT | 0x15B1 | BizTalk Server failed to access the "%1" database on the "%2" server with the database connection information.
CIS_E_ADMIN_PURGE_SUSPENDEDQ | 0x15B2 | An instance of the "%1" object could not be created while deleting documents from "%2".
CIS_E_ADMIN_REQ_PROP_MISSING | 0x15B3 | %1 cannot be NULL.
CIS_E_ADMIN_WMI_ERROR_HANDLING | 0x15B4 | The BizTalk Server WMI provider error-handling method failed. The original error description for the error that called the error-handling method is: "%1".
CIS_W_ADMIN_QUERY_FAILED | 0x15B5 | An attempt to get the Where clause values for a WMI Query failed.
CIS_E_ADMIN_INVALID_ENUM_CONSTRAINT | 0x15B6 | The value "%2" of the "%1" property is not valid.
CIS_E_ADMIN_OPENNESS_CONSTRAINT | 0x15B7 | The value "%2" of the "%1" property is not permitted when the value of the IsPassThrough property is set to TRUE.
CIS_E_ADMIN_RECEIVE_INVALID_SERVER_GROUP | 0x15B8 | the specified server and/or group is not valid
CIS_E_ADMIN_INVALID_INSTANCE_NAME | 0x15B9 | The specified instance name "%1" contains at least one of the following characters that is not valid: [ ` ~ ! @ # $ % ^ & * ( ) + = [ ] { } | \ ; " ' < > , . ? ]
BTS_E_ADMIN_GROUP_UNIQUE_NAME | 0x15BA | A BizTalk Server group with the same name already exists in the BizTalk Messaging Management database.
BTS_E_ADMIN_TIMESTAMPS_DATA_CORRUPTION | 0x15BB | Internal data corruption has been detected in the adm_TimeStamps table of the BizTalk Messaging Management database.
BTS_E_ADMIN_SERVER_UNIQUE_NAME | 0x15BC | A BizTalk Server with the same name already exists in the BizTalk Messaging Management database.
BTS_E_ADMIN_SERVER_FOREIGN_GROUPNAME | 0x15BD | This BizTalk Server does not reference a valid BizTalk Server group in the BizTalk Messaging Management database.
BTS_E_ADMIN_RECSVC_UNIQUE_NAME | 0x15BE | A BizTalk Server receive function with the same name already exists in the BizTalk Messaging Management database.
BTS_E_ADMIN_RECSVC_FOREIGN_GROUPNAME | 0x15BF | This BizTalk Server receive function does not reference a valid BizTalk Server group in the BizTalk Messaging Management database.
BTS_E_ADMIN_UNIQUE_HTTP_POLLING_LOCATION | 0x15C0 | An HTTP receive function polling from the same location already exists in the BizTalk Messaging Management database.
BTS_E_ADMIN_PARSER_UNIQUE_ID | 0x15C1 | A BizTalk Server parser with the same CLSID and Group Name already exists in the BizTalk Messaging Management database.
BTS_E_ADMIN_PARSER_FOREIGN_GROUPNAME | 0x15C2 | This BizTalk Server parser does not reference a valid BizTalk Server group in the BizTalk Messaging Management database.
CIS_E_ADMIN_DB_SPROCVERSION | 0x15C3 | The "%1" database on the "%2" server does not contain the necessary database schema.
CIS_E_ADMIN_DB_VERSION | 0x15C4 | The "%1" database on the "%2" server is not compatible with the current version of the product.
CIS_E_ADMIN_CREATE_CUSTOM_COUNTER | 0x15D0 | The custom counter cannot be created because "%1".
CIS_E_ADMIN_LOAD_CUSTOM_COUNTER_PROPS | 0x15D1 | The custom counter cannot be loaded because "%1".
CIS_E_ADMIN_SAVE_CUSTOM_COUNTER_PROPS | 0x15D2 | The custom counter cannot be saved because "%1".
CIS_E_ADMIN_REMOVE_CUSTOM_COUNTER_PROPS | 0x15D3 | The custom counter cannot be removed because "%1".
CIS_E_ADMIN_NOCUSTOM_COUNTER | 0x15D4 | The specified custom counter could not be found. Verify that the name of the specified custom counter is correct.
CIS_E_ADMIN_UNEXPECTED_REMOVE_CUSTOM_COUNTER | 0x15D5 | An unexpected error occurred while trying to remove the "%1" custom counter from the database.
CIS_E_ADMIN_VALIDATE_COUNTER_PROPS | 0x15D6 | The custom counter cannot be validated because "%1".
CIS_E_ADMIN_GET_VALUE_CUSTOM_COUNTER_PROPS | 0x15D7 | The value of the custom counter cannot be evaluated because "%1".
CIS_E_ADMIN_UNEXPECTED_VALIDATE_CUSTOM_COUNTER | 0x15D8 | An unexpected error occurred while trying to validate the "%1" custom counter.
CIS_E_ADMIN_CUSTOM_COUNTER_ORG_CONSTRAIN | 0x15D9 | Either both %1 and %2 properties must be empty or %3 property must be empty.
CIS_E_ADMIN_WRONG_HTTP_POLLING_LOCATION | 0x15DA | The "%1" property is incorrect for the HTTP receive function ( http://... expected).
CIS_E_DTA_LOG_INTERCHANGE_DETAILS_FAILED | 0x1604 | The details of an interchange could not be logged.
CIS_E_DTA_LOG_DOCUMENT_DETAILS_FAILED | 0x1605 | The details of a document could not be logged.
CIS_E_DTA_LOG_GROUP_DETAILS_FAILED | 0x1606 | The details of a group could not be logged.
CIS_E_DTA_INIT_FAILED | 0x160A | The DTA object could not be initialized.
CIS_E_DTA_FAILED_TO_GET_ADMIN_PROPERTIES | 0x160E | The administration properties could not be obtained.
CIS_E_DTA_DATABASE_CONNECTION | 0x160F | The server could not establish connection to the Tracking database.
CIS_E_DTA_LOG_DOCUMENT_FAILED | 0x1619 | A copy of the document could not be logged.
CIS_E_DTA_LOG_INTERCHANGE_FAILED | 0x1620 | A copy of the interchange could not be logged.
CIS_E_DTA_OBJECT_IS_UNINITIALIZED | 0x1623 | The DTA initialization method must be explicitly invoked before any DTA method can be invoked.
CIS_E_DTA_FAILED_TO_COMMIT | 0x1625 | Changes could not be committed to the database.
CIS_E_DTA_FAILED_TO_LOG_SOURCE_XML | 0x1626 | The intermediate source XML could not be logged.
CIS_E_DTA_FAILED_TO_LOG_DEST_XML | 0x1627 | The intermediate destination XML could not be logged.
CIS_E_DTA_ACK_NO_ROW_FOUND | 0x162B | Acknowledgment correlation failed. The correlation key(s) given did not match any record in the Tracking database.
CIS_E_DTA_ACK_MULTIPLE_ROWS_FOUND | 0x162C | Acknowledgment correlation failed. The correlation key(s) given match more than one record in the Tracking database.
CIS_E_DTA_LOG_MIME_FAILED | 0x162D | The MIME data for submission "%1" could not be logged.
CIS_W_DTA_LOG_TRACKING_FIELD_FAILED | 0x162E | The following tracking field for submission "%1" could not be logged: Tracking field: %2 Specification field name: %3 Actual value: %4 Possible causes are either a conversion error or an arithmetic overflow error. Check the tracking field settings in the document or channel configuration.
CIS_W_DTA_LOG_BINARY_TRACKING_FIELD_FAILED | 0x162F | The following tracking field for submission "%1" could not be logged: Tracking field: %2 Specification field name: %3 The submission could not be logged because the corresponding XML element or attribute is set to binary type, which can only be tracked as custom type tracking field. Correct the tracking field settings in the document or channel configuration.
CIS_E_DTA_INIT_TRANSACTIONAL_SESSION | 0x1631 | The server could not create a transactional session for the Tracking object.
CIS_W_DTA_RECORD_UPDATE_FAILED | 0x1632 | An attempt to update a tracking record has failed. The record was probably deleted prior to the update action.
CIS_E_RESPONSE_DOM_LOAD_FAILED | 0x1701 | The XML-DOM could not be loaded from the response data.
CIS_E_RECEIVE_MSMQ_BYOT_CREATE_FAILED | 0x1702 | A Message Queuing receive function failed to create an IInterchange object using a Bring Your Own Transaction (BYOT) object. This may have been caused by editing the BizTalk Server COM+ application or configuring the BYOT object in its own COM+ application. This BizTalk Message Queuing receive function will be stopped.
CIS_E_RECEIVE_MSMQ_ZERO_BYTE_DOC | 0x1703 | A Message Queuing receive function read a zero byte document. This document has been discarded.
CIS_E_RECEIVE_SERVICE_FAILED | 0x1704 | There was a failure processing the "%1" receive function. Check your receive function configuration in BizTalk Server Administration.
CIS_E_INITWORKITEM | 0x1705 | There was a failure creating the internal work item. Make sure that SQL Server is running.
CIS_E_NOPIPELINE | 0x1706 | A channel with the name "%1" cannot be located.
CIS_E_OPEN_PASSTHROUGH | 0x1707 | The channel and messaging port openness type are not compatible with the submit method call.
CIS_E_DLQ_DETAILS | 0x1708 | Details about the Suspended queue could not be retrieved.
CIS_E_INVALID_OPENDEST | 0x1709 | The destination specified for the following open-destination messaging port was not valid: %1
CIS_E_SQL_MISSINGROWS | 0x170a | Rows were missing from the record returned by SQL OLEDB provider.
CIS_E_BTF_TIME_STAMP_EXPIRED | 0x170b | The BizTalk Framework document "%1" was received with an expired "%2" timestamp. This message will be discarded.
CIS_E_ACCESS_DENIED | 0x170c | The current process did not have administrative privileges and cannot access the Suspended queue.
CIS_E_BTF_ERROR_FINDING_TAG | 0x170d | The parser could either not find the BizTalk Framework tag "%1", or the tag did not have a value. This document will be moved to the Suspended queue.
CIS_E_INVALID_FORMAT | 0x170e | The "%1" envelope format is not recognized by the server. Specify a valid envelope format.
CIS_E_INVALID_MAP | 0x170f | The server could not load the map that is referenced by this channel.
CIS_E_MALFORMED_EXPR | 0x1710 | The expression "%1" is malformed and cannot be interpreted by the server.
CIS_E_DB_SHUTDOWN | 0x1711 | The server is shutting down because of a database failure.
CIS_E_SUBMIT_BLOCKED | 0x1712 | All submit calls have been blocked due to a database failure. After correcting this problem, please go to Component Services and shut down the 'BizTalk Server Interchange Application', before attempting to call any submit method.
CIS_E_CERT_NOT_FOUND | 0x1713 | The required certificate cannot be found in the certificate store.
CIS_E_NODATA | 0x1714 | The Submit method call did not contain a document or a file path.
CIS_E_TOOMUCH_DATA | 0x1715 | The Submit method call contained both a document and a file path.
CIS_E_INVALID_OPENFLAG | 0x1716 | The Submit method call was passed an openness type that is not valid. Refer to the BizTalk Server 200 Help documentation for the enumeration of these values.
CIS_E_PASSTHROUGH_PARAMS | 0x1717 | The Submit method call contained a channel along with source, destination, or document name information. Do not include source, destination, or document name information when passing the channel as a parameter within a Submit method call.
CIS_E_NOSRCID | 0x1718 | The Submit method call contained a source qualifier but no source identifier.
CIS_E_NODESTID | 0x1719 | The Submit method call contained a destination qualifier but no destination identifier.
MSG_TIMEBOMB_EXPIRED | 0x171A | Thank you for evaluating Microsoft BizTalk Server. The period for this evaluation version has ended. Please contact Microsoft or your software reseller to obtain a licensed version of Microsoft BizTalk Server.
CIS_E_LOOPBACK | 0x171B | An attempt was made to submit a document that uses the Loopback transport type. The Loopback transport type can only be used when calling the SubmitSync method.
CIS_E_DBEXECUTE | 0x171C | The following stored procedure call failed: "%1".
CIS_E_MISSING_SMTPHOST | 0x171D | In order to use the SMTP transport, the SMTP host must be specified. To specify an SMTP host, in BizTalk Server Administration expand Microsoft BizTalk Server 200, right-click BizTalk Server Group, and then click Properties to open the BizTalk Server Group Properties dialog box. On the General tab, in the SMTP host box, specify the SMTP host that you want to use.
CIS_E_INVALIDHANDLE | 0x171E | This method expected a submission handle or an array of submission handles, but the incoming data was not valid. Verify that the parameters are correct.
CIS_E_DBCONNECT | 0x171F | BizTalk Server failed to initialize a connection to database: "%1" on server: "%2".
CIS_E_PASSTHROUGH_WITH_NOCHANNEL | 0x1720 | A valid channel name must be specified as a submission parameter on a Submit or SubmitSync method call when the pass-through flag is set to true.
CIS_W_DBFAILURE | 0x1721 | The database call failed and returned the following error string: "%1". If possible, we will attempt to retry this call.
CIS_E_GET_BTMPARAMS | 0x1722 | Unable to load connection parameters for BTM database. Please go to the Administration MMC to resolve this problem.
CIS_E_UNABLE_TO_CREATE_CUSTOM_PRE_PROC | 0x1723 | The custom preprocessing component for the receive function "%1" could not be created. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_FAILED | 0x1724 | The custom preprocessing component used by the receive function "%1" failed. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_NO_BSTR | 0x1725 | The custom preprocessing component used by the File receive function "%1" failed to return a valid BSTR. A valid BSTR is required. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_INVALID_DATA | 0x1726 | The custom preprocessing component used by the Message Queue receive function "%1" cannot be called because the message contains data that is not a BSTR or a BYTE array. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_INVALID_CP | 0x1727 | The custom preprocessing component used by the Message Queue receive function "%1" failed to return a valid code page. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_INVALID_DATA_OUT | 0x1728 | The custom preprocessing component used by the Message Queue receive function "%1" failed to return a valid document, the document must be either a BSTR or a BYTE array. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_FILE_PRE_PROC_FAIL | 0x1729 | The custom preprocessing component used by the file receive function "%1" failed. The document "%2" will be moved to the Suspended queue.
CIS_E_CUSTOM_PRE_PROC_CANT_SET_CTX | 0x172A | The server was unable to set the context on the custom preprocessing component used by the receive function "%1". This document will be moved to the Suspended queue.
CIS_E_FILERCV_FILE_SHARE_DOWN | 0x172B | The file receive function "%1" was unable to connect to the network share "%2". This receive function will try to connect again.
CIS_E_FILERCV_NETWORK_DOWN | 0x172C | The file receive function "%1" is experiencing network problems and was unable to connect to the network share "%2". This receive function will try to connect again.
CIS_E_RECEIVE_FUNCTION_DISABLED | 0x172D | The receive function "%1" has experienced problems, it will be shut down and disabled. Once these problems have been corrected, re-enable this receive function in BizTalk Server Administration.
CIS_E_UNRECOVERABLE | 0x172E | There was a serious error within the BizTalk Server scheduler component. The server is being shut down. Resolve this problem and then restart the server.
CIS_E_RELIABLE_NOACK | 0x172F | The server has not received a receipt for the reliable message.
CIS_E_DLQ_ID | 0x1730 | Suspended Queue ID: "%1"
CIS_E_CANNOT_FIRE_EVENT | 0x1731 | The server cannot send a WMI event for the Suspended queue item "%1". The most likely cause is that the user configured for this submission has insufficient privileges to access WMI.
CIS_E_HTTP_L_INITIALIZATION | 0x1750 | The BizTalk HTTP receive function could not complete initialization. Verify that the security credentials of "BizTalkHTTPReceive.dll" include access to the BizTalk configuration database.
CIS_E_HTTP_L_NO_DATA_SEND | 0x1751 | The BizTalk HTTP receive function "%1" received a request with no data.
CIS_E_HTTP_L_NO_THREAD_FROM_POOL | 0x1752 | The BizTalk HTTP receive function "%1" could not retrieve a thread from the thread pool.
CIS_E_HTTP_L_NO_TRANSPORT | 0x1753 | The BizTalk HTTP receive function could not select a valid transport. Check the configuration of this receive function: Request URL="%1".
CIS_E_HTTP_L_SERVER_SUPP_FUNCT | 0x1754 | The BizTalk HTTP receive function "%1" made a call to IIS Server Support Function: "%2" which failed.
CIS_E_HTTP_L_POST_THREAD_POOL | 0x1755 | The BizTalk HTTP receive function "%1" could not post the work item to the thread pool. Try increasing the length of the thread pool queue using the registry key "QueueFactor".
CIS_E_HTTP_L_GET_FROM_THREAD_POOL | 0x1756 | The BizTalk HTTP receive function "%1" could not retrieve a work item from the thread pool.
CIS_E_HTTP_L_SEND_HEADERS | 0x1757 | The BizTalk HTTP receive function "%1" could not send the HTTP headers to the client.
CIS_E_HTTP_L_ASYNC_PROCESSING | 0x1758 | The BizTalk HTTP receive function "%1" failed during asynchronous processing of an IIS request.
CIS_E_HTTP_L_ASYNC_IIS_ERROR | 0x1759 | The BizTalk HTTP receive function "%1" received an error from IIS while processing an asynchronous request.
CIS_E_HTTP_L_DLL_LOAD_FAILURE | 0x175A | The BizTalk HTTP receive function could not load the DLL "%1".
CIS_E_HTTP_L_CREATION_FAILURE | 0x175B | The BizTalk HTTP receive function could not create "%1", error:"%2".
CIS_E_HTTP_L_TRANSPORT_URL | 0x175C | The BizTalk HTTP receive function could not extract a valid transport URL from the request URL. Error:"%1". Request URL="%2".
CIS_E_HTTP_L_TRANSPORT_URL_INVALID | 0x175D | The BizTalk HTTP receive function transport alias "%1" is not valid. Check the configuration of this receive function.
CIS_E_HTTP_L_TRANSPORT_HANDLE_INVALID | 0x175E | The BizTalk HTTP receive function transport handle for alias "%1" is not valid. Check the configuration of this receive function.
CIS_E_HTTP_L_FILE_CREATION_FAILURE | 0x175F | The BizTalk HTTP receive function "%1" could not create the file "%2".
CIS_E_HTTP_L_SET_FILE_POINTER_FAILURE | 0x1760 | The BizTalk HTTP receive function "%1" could not set the file pointer while writing to the file "%2".
CIS_E_HTTP_L_FILE_WRITE_FAILURE | 0x1761 | The BizTalk HTTP receive function "%1" could not write to the file "%2".
CIS_E_HTTP_L_FILE_LOCK_FAILURE | 0x1762 | The BizTalk HTTP receive function "%1" could not obtain a lock on the file "%2".
CIS_E_HTTP_L_BUILD_FILE_NAME_FAILURE | 0x1763 | The BizTalk HTTP receive function "%1" could not build a valid file name for "%2.
CIS_E_HTTP_L_FILE_DELETE_FAILURE | 0x1764 | The BizTalk HTTP receive function "%1" could not delete the file "%2".
CIS_E_HTTP_L_DETERMINING_CODE_PAGE | 0x1765 | The BizTalk HTTP receive function "%1" could not retrieve the code page for charset="%2".
CIS_E_HTTP_L_MSMQ_SEND_FAILURE | 0x1766 | The BizTalk HTTP receive function could not send a message to the message queue "%1", HR=%2, Request URL:"%3".
CIS_E_HTTP_L_MSMQ_OPEN_FAILURE | 0x1767 | The BizTalk HTTP receive function could not open the message queue "%1", HR=%2.
CIS_E_HTTP_L_REGISTRY_FAILURE | 0x1768 | The BizTalk HTTP receive function could not retrieve the configuration from the registry.
CIS_E_HTTP_L_CP_CONVERTION_FAILURE | 0x176A | The BizTalk HTTP receive function "%1" encountered an error converting the document to UNICODE.
CIS_E_HTTP_L_SUBMIT_FAILED | 0x176B | The BizTalk HTTP receive function "%1" failed to submit the document into BizTalk Messaging.
CIS_E_HTTP_L_SERVER_VARIABLE | 0x176C | The BizTalk HTTP receive function could not successfully retrieve the server variable "%1" from IIS, error:%2.
CIS_E_HTTP_L_BASE_URL_NOT_OBTAINABLE | 0x176D | The BizTalk HTTP receive function could not retrieve the URL from IIS.
CIS_E_HTTP_L_SUBMISSION_HANDLE_ERROR | 0x176E | The BizTalk HTTP receive function "%1" could not send the BizTalk correlation token to the client.
CIS_E_HTTP_L_GET_CONFIG_ERROR | 0x176F | The BizTalk HTTP receive function could not successfully retrieve the configuration information from the database, hr=%1.
CIS_E_HTTP_L_IMPERSNT_FAILED | 0x1770 | The BizTalk HTTP receive function could not get the appropriate security credentials to access the database.
CIS_E_HTTP_L_WRITE_RESPONSE_ERROR | 0x1771 | The BizTalk HTTP receive function "%1" could not send the HTTP response to the client.
CIS_E_HTTP_L_SUBMITSYNC_FAILED | 0x1772 | The BizTalk HTTP receive function "%1" could not synchronously submit the document to BizTalk Messaging.
CIS_E_HTTP_L_MOVETOSUSPENDQ_FAILED | 0x1773 | The BizTalk HTTP receive function "%1" could not move the document received to the Suspended Queue.
CIS_E_SERIALIZER_INVALID_DOCUMENT | 0x1800 | The document with the "%1" tracking identifier is invalid XML. The serializer cannot continue.
CIS_E_BTF_INVALID_ADDRESS_TYPE | 0x1801 | The BizTalk Framework document has an "type" specified that is not valid for the "%1" address field. This document will be moved to the Suspended queue.
CIS_E_RELIABLE_MSG_RECEIPT_REQ_BY | 0x1802 | The BizTalk Framework document "%1" will not be transmitted as it has an expired "receiptRequiredBy" timestamp. This message will be discarded.
CIS_E_CUSTOM_ENVELOPE_ERROR | 0x1803 | The custom envelope:"%1" had the property "%2" specified, but the custom envelope generator could not to locate the XML node. This document will be moved to the Suspended queue.
CIS_E_SERIALIZER_INVALID_DATETIME | 0x1804 | The "%1" date or time format is not valid. Correct the format specification.
CIS_E_SERIALIZER_INVALID_DTDATA | 0x1805 | The "%1" date or time field is not a valid ISO8601 format. Make sure that the XML date or time is formatted correctly.
CIS_E_SERIALIZER_INVALID_DELIMITER | 0x1806 | The "%1" delimiter is either missing or has a value specified that is not valid. Update the delimiter value.
CIS_E_SERIALIZER_MISSING_PROPSET | 0x1807 | The "%1" document is missing the entire property set that is required for this serializer to run.
CIS_E_SERIALIZER_MISSING_PROP | 0x1808 | The property set for the "%1" document either is missing or does not contain a valid value for the "%2" property. Add or correct this property.
CIS_E_SERIALIZER_INVALIDARG | 0x1809 | Both source and destination qualifiers and values are required for this serializer to run. Specify qualifiers and values in the messaging port for this transaction.
CIS_E_SERIALIZER_MISMATCH_SPEC | 0x180A | The serialization produced no output. Verify that the document specification matches the outbound XML document.
CIS_E_SERIALIZER_FAILED | 0x180B | The serializer could not finish processing. See the following messages for details.
CIS_E_SERIALIZER_INVALID_SRCQUAL | 0x180C | The "%1" qualifier for the source identifier is too long to be placed in the outbound document header. Update the channel with a shorter qualifier.
CIS_E_SERIALIZER_INVALID_SRCID | 0x180D | The "%1" value for the source identifier is too long to be placed in the output header. Update the channel with a shorter value.
CIS_E_SERIALIZER_INVALID_DESTQUAL | 0x180E | The "%1" qualifier for the destination identifier is too long to be placed in the output header. Update the port with a shorter qualifier.
CIS_E_SERIALIZER_INVALID_DESTID | 0x180F | The "%1" value for the destination identifier is too long to be placed in the output header. Update the port with a shorter identifier.
CIS_E_SERIALIZER_INVALID_POSREC | 0x1810 | The "%1" positional record is defined to contain a record length of zero. This happens when there is no tag, and none of the fields in this record specify start and end positions. Update the fields to have valid start and end positions for this record.
CIS_E_SERIALIZER_NODELIMS | 0x1811 | This serializer component requires delimiters specified in the messaging port. Specify a valid delimiter set for this component.
CIS_E_SERIALIZER_INVALID_CHAR | 0x1812 | The serializer component has encountered a character, "%1", that is not valid. An entry specified in the InvalidCharacterMap tag of the document specification states that characters between "%2" and "%3" are not valid.
CIS_E_SERIALIZER_INVALID_LENGTH | 0x1813 | The length of the "%1" field ("%2") is not valid; it must be between %3 and %4. This document will be rejected.
CIS_E_SERIALIZER_SELECT_SINGLE_NODE_FAILED | 0x1814 | The serializer component cannot find the node using the query "%1". This document will be rejected.
CIS_E_SERIALIZER_RELIABLE_URL_MISSING | 0x1815 | The reply-to URL required for reliable messaging was not set. This document will be rejected.
CIS_E_SERIALIZER_CONTROL_NUMBER | 0x1816 | The serializer component cannot find a control number for %1 %2 in the BizTalk Management database. This document will be rejected.
CIS_E_CUSTOM_ENV_PARSE_TABLE_ERROR | 0x1817 | The serializer component failed to build the custom envelope ID:"%1", this was due to errors in the XML Schema supplied. This document will be moved to the Suspended queue.
CIS_E_SUBSYNC_RELIABLE_MSG | 0x1818 | The BizTalk Framework document that was submitted has "reliability" information specified. This information is not permitted in a synchronous call.
CIS_E_CUSTXML_BODY_NOT_FOUND | 0x1819 | The parser was unable to locate the XML document node by using the query specified in the XML specification: "%1".
CIS_E_BTF_ACK_BAD_MSG_ID | 0x181A | The BizTalk Framework receipt had a <prop:identity> tag that is not valid: "%1". This document will be moved to the Suspended queue.
CIS_E_BTF_MANIFEST_REF_MISSING | 0x181B | The BizTalk Framework document has a <manifest> tag without the mandatory <reference> tag. This document will be moved to the Suspended queue.
CIS_E_CUSTOM_ENV_NO_DOC_NODE | 0x181C | The serializer failed to create the custom envelope because the Document Container Node property was not specified in the XML specification. This document will be moved to the Suspended queue.
CIS_E_BTF_INVALID_XSI_TYPE | 0x181D | The BizTalk Framework document contains an xsi:type attribute "%1" that is not valid. This attribute must not have spaces, and the first character must be alphabetical. This document will be moved to the Suspended queue.
CIS_E_SERIALIZER_INVALID_SYNTAX_IDENTIFIER | 0x181E | The EDIFACT Syntax Identifier "%1" is not valid. Update the channel with a correct identifier.
CIS_E_SERIALIZER_INVALID_UNA_CONTROL | 0x181F | The EDIFACT UNA Control value "%1" is not valid. Update the channel with a correct value.
CIS_E_SERIALIZER_EXPECT_BSTR_VALUE | 0x1820 | The configuration data for the field "%1" must be a string. Update the data for this field.
BTS_E_XMLSERIALIZER_MISSING_DEST | 0x1821 | The BizTalk Framework header could not be generated because no destination identifier was specified.
BTS_E_XMLSERIALIZER_MISSING_SRC | 0x1822 | The BizTalk Framework header could not be generated because no source identifier was specified.
CIS_E_BTF_IDENTITY_MISSING | 0x1904 | The parser could not find the mandatory BizTalk Framework tag "identity". This document will be moved to the Suspended queue.
CIS_E_BTF_EXPIRESAT_MISSING | 0x1905 | The parser could not find the mandatory BizTalk Framework tag "expiresAt". This document will be moved to the Suspended queue.
CIS_E_MSMQ_NOT_INSTALLED | 0x1906 | The Message Queuing receive function could not be started because the Message Queuing service is not installed on the server.
CIS_W_FILE_RECEIVE_RETRY_FAILURE | 0x1907 | There are file(s) in the "%1" directory that cannot be accessed by the file receive function. The receive service will try again to access the file(s) in "%2" seconds.
CIS_E_FILE_RECEIVE_DELETE_FAILURE | 0x1909 | The following file could not be deleted after processing: "%1". Make sure that the file attribute is not set to read-only.
CIS_E_LOGON_USER_FAILURE | 0x190a | Unable to logon with the account %1. Make sure that %2 has been granted "logon locally" privilege on this server and that the BizTalk Server account has "act as part of the operating system" privilege.
CIS_E_MSMQ_RECEIVE_IMPERSONATION_FAILURE | 0x190b | The "%1" Message Queuing receive function could not impersonate the logged on user.
CIS_E_RECEIVE_CANNOT_CREATE_THREAD | 0x190c | A receive-function thread cannot be created due to a system error.
CIS_E_MSMQ_RECEIVE_OPENQ_FAILURE | 0x190d | The following Message Queuing queue cannot be opened: "%1" (Message Queuing error code: 0x%2=%3). Verify the existence and security setting of the queue.
CIS_E_MSMQ_RECEIVE_PEEKQ_FAILURE | 0x190e | The Message Queuing queue could not be read: "%1" (Message Queuing error code: 0x%2=%3).
CIS_E_MSMQ_RECEIVE_RETRIEVEQ_FAILURE | 0x190f | A message could not be retrieved from the following Message Queuing queue: '%1' (Message Queuing error: 0x%2=%3).
CIS_E_FILE_RECEIVE_FINDCHANGE_FAILURE | 0x1910 | The file-change notification cannot be set up on the following directory: "%1". Make sure that the path is correct.
CIS_E_SET_CURRENT_DIR_FAILURE | 0x1911 | The current directory cannot be set to: "%1". Make sure that the path is correct.
CIS_W_RECEIVE_SUBMIT_FAILURE | 0x1914 | A submit request initiated from the "%1" receive function has failed.
CIS_E_READONLY_FILE | 0x1915 | The "%1" receive function picked up the following file: '%2'. This file is marked as read-only and cannot be processed.
CIS_E_BAD_RECSVC | 0x1916 | There was a serious failure in the receive function "%1". This receive service will be shut down, please check the event log for additional error messages.
CIS_E_FILE_RECEIVE_IMPERSONATION_FAILURE | 0x1917 | The "%1" file receive function could not impersonate the logged on user.
CIS_E_MSMQ_RECEIVE_UNEXPECTED_PASSTHROUGH | 0x1918 | The ""%1"" Message Queuing receive function is not configured for a pass-through submission, but it has encountered a document that was submitted previously as a pass-through submission. Change this receive function to accept pass-through submissions or remove the pass-through document from the queue. This receive function will be shut down.
CIS_E_BTSDOCUMENT_INVALIDNAME | 0x1A00 | The document named "%1" does not exist. Correct the document name or add the document to the BizTalk Messaging Management database.
CIS_E_BTSDOCUMENT_INVALIDDOC | 0x1A01 | The server could not load any documents with the given criteria.
CIS_E_BTSDOCUMENT_AMBIGUOUS_NAMESPACE | 0x1A02 | The root node "%1" is ambiguous because documents "%2" and "%3" refer to different specifications with that name. Either change the specifications to remove this ambiguity or use the document name explicitly.
CIS_E_BTSDOCUMENT_AMBIGUOUS_PROPSET | 0x1A03 | The property set is ambiguous because documents "%1" and "%2" refer to the same property set.
CIS_E_BTSDOCUMENT_AMBIGUOUS_PROPSETSHAREID | 0x1A04 | The property set is ambiguous because documents "%1" and "%2" refer to the same property set and have reference "%3".
CIS_E_BTSDOCUMENT_INVALIDPROPERTYSET | 0x1A05 | The following property set was specified: %1.
CIS_E_BTSDOCUMENT_EMPTYPROPERTYSET | 0x1A06 | The property set was empty.
CIS_E_BTSDOCUMENT_LOADFAILED | 0x1A07 | The document "%1" could not be loaded. Possible causes are using a non-envelope specification, or incorrectly configured tracking details.
CIS_E_BTSENVELOPE_LOADFAILED | 0x1A20 | The envelope "%1" could not be loaded. A possible cause is that the specification is not valid. Configure a valid envelope specification.
CIS_E_FAILED_TO_JOIN_TX | 0x1A21 | BizTalk Server failed to join a transaction. Ensure both the DTC and the SQL Server database are running.
MSG_COM_CREATE_FAILED | 0x1B01 | An instance of the %1 class cannot be created: %2.
MSG_CONNECT_WMI_FAILED | 0x1B02 | A connection to Windows Management on "%1" cannot be established: %2.
MSG_COSETPROXY_FAILED | 0x1B03 | The authentication credential cannot be set for the Windows Management connection: %1.
MSG_WMI_ENUMINST_FAILED | 0x1B04 | Instances of the BizTalk Server WMI provider class "%1" cannot be enumerated: %2.
MSG_WMI_GETPROP_FAILED | 0x1B05 | The property value of "%1" cannot be retrieved from the BizTalk Server WMI provider because of an unexpected error: %2.
MSG_WMI_EXECQUERY_FAILED | 0x1B06 | An unexpected error is preventing execution of the BizTalk Server WMI provider query "%1": %2.
MSG_WMI_GETOBJ_FAILED | 0x1B07 | The BizTalk Server WMI provider instance of "%1" cannot be retrieved because of an unexpected error: %2.
MSG_WMI_PUTPROP_FAILED | 0x1B08 | The property value of "%1" cannot be changed because of an unexpected error: %2.
MSG_WMI_PUTINST_FAILED | 0x1B09 | The property values of the BizTalk Server WMI provider instance "%1" cannot be updated because of an unexpected error: %2.
MSG_WMI_DELINST_FAILED | 0x1B0A | The BizTalk Server WMI provider instance "%1" cannot be deleted because of an unexpected error: %2.
MSG_WMI_CREATEINST_FAILED | 0x1B0B | A new instance of the WMI class "%1" cannot be created in the BizTalk Server WMI provider: %2.
MSG_WMI_CREATEGETOBJ_FAILED | 0x1B0C | A new instance of the BizTalk Server WMI provider class "%1" cannot be created because of an unexpected error: %2.
MSG_WMI_EXECMETHOD_GETOBJ_FAILED | 0x1B0D | The method "%1" of the BizTalk Server WMI provider class "%2" cannot be executed because of a failure to retrieve the class: %3.
MSG_WMI_EXECMETHODCLASS_FAILED | 0x1B0E | The method "%1" of the BizTalk Server WMI provider class "%2" cannot be executed because of a failure to retrieve the method information: %3.
MSG_WMI_EXECMETHODSPAWN_FAILED | 0x1B0F | The method "%1" of the BizTalk Server WMI provider class "%2" cannot be executed because of an unexpected error: %3.
MSG_WMI_EXECMETHODPUTPARAM_FAILED | 0x1B10 | The method "%1" of the BizTalk Server WMI provider class "%2" cannot be executed because of a failure to set the parameter value: %3.
MSG_WMI_EXECMETHOD_FAILED | 0x1B11 | The method "%1" of the WMI class "%2" cannot be executed by the BizTalk Server WMI provider: %3.
MSG_GET_HOSTNAME_FAILED | 0x1B12 | The local computer name cannot be obtained because of an unexpected error: %1.
MSG_OUT_OF_MEMORY | 0x1B14 | Insufficient memory.
MSG_FAIL_LOAD_BMP | 0x1B17 | At least one of the bitmaps cannot be loaded in the BizTalk Server Administration console: %1.
MSG_FAIL_SET_BMPSTRIP | 0x1B18 | At least one pair of bitmaps cannot be added to the image list of the BizTalk Server Administration console: %1.
MSG_ERROR_WMI_PATH_EMPTY | 0x1B19 | The requested operation cannot be completed because of a previous WMI failure. The WMI object path is empty in this case.
MSG_ERROR_BTM_GRP_ENUM_FAIL | 0x1B20 | Unknown problems are preventing the WMI provider from enumerating a list of server groups from the BizTalk Messaging Management database: %1.
MSG_ERROR_GRP_DTA_DB_FAIL | 0x1B21 | Unknown problems are preventing the WMI provider from accessing the Tracking database for the "%1" group.
MSG_ERROR_GRP_SQ_DB_FAIL | 0x1B22 | Unknown problems are preventing the WMI provider from accessing the Shared Queue database the "%1" group.
MSG_ERROR_GRP_BOTH_DB_FAIL | 0x1B23 | Unknown problems are preventing the WMI provider from accessing the Tracking and Shared Queue databases for the "%1" group.
MSG_ERROR_DECRYPT_FAIL | 0x1B24 | Password decryption failed: %1.
MSG_WARN_ENUM4ROOTUPD_FAILED | 0x1B27 | Unknown problems are preventing the WMI provider from retrieving following list of servers and their states to prepare for BizTalk Messaging Management database update: %1
MSG_ERROR_CHANGE_ROOTDB | 0x1B28 | The server "%1" cannot be updated with the new BizTalk Messaging Management database information: %2.
MSG_ERROR_CHANGE_ROOTDB_CONNECT | 0x1B29 | We cannot connect to the WMI namespace "%1" to update server "%2" with the new BizTalk Messaging Management database information: %3
MSG_CHANGE_ROOTDB_SUMMARY | 0x1B30 | The BizTalk Messaging Management database change request has been completed. %1%2 %3%4
MSG_CHANGE_ROOTDB_ON_LOCAL | 0x1B3A | Because the server and server group information cannot be retrieved from the original BizTalk Messaging Management database, the BizTalk Messaging Management database information will be updated only on the local computer "%1". The update has been successful.
MSG_ERROR_UNEXPECTED_ENDOFLIST | 0x1B3C | An unexpected end of list (EOL) for the "%1" class enumeration has been reached.
MSG_ERROR_ORG_QUALIFIERS_FROM_DB_FAILED | 0x1B3D | The organization qualifiers cannot be retrieved from the BizTalk Messaging Management database because of an unexpected error. "%1".
MSG_ERROR_ORG_VALUES_FROM_DB_FAILED | 0x1B3E | The organization values cannot be retrieved from the BizTalk Messaging Management database because of an unexpected error. "%1".
MSG_WARN_NOT_RESUBMITABLE | 0x1B3F | In the selected group of multiple items, at least one item cannot be submitted again.
MSG_WARNING_PROP_VALUES_CHANGED | 0x1B40 | %1 "%2" specified for receive function "%3" has been removed from the BizTalk Messaging Management database.
MSG_WARNING_QUALIFIER_CHANGED | 0x1B41 | The qualifier and identifier pair "%1" and "%2" specified for receive function "%3" is not valid in the BizTalk Messaging Management database.
MSG_WARNING_ORGANIZATION_CHANGED | 0x1B42 | Organization "%1" specified for receive function "%2" is not valid in the BizTalk Messaging Management database.
MSG_TIMEBOMB_DAYS_LEFT | 0x1B43 | Thank you for evaluating Microsoft BizTalk Server. The period for this evaluation version has %1 days left. Please contact Microsoft or your software reseller to obtain a licensed version of Microsoft BizTalk Server.
INTERCHANGE_EVENT | 0x3005 | BizTalk Server: %1

Note

  • When an error occurs, the %n variables are replaced with relevant information, such as an object name.


Orchestration Services Error Messages

The BizTalk Orchestration Services object model error messages in the following table are returned when a running XLANG schedule generates the warning or error. These messages can be viewed in Windows® 2000 Event Viewer.

Message name | Value | Description
ID_W_NOT_CREATOR | 0x1000 | An unauthorized client attempted to create a new instance of an XLANG schedule. The remainder of the moniker string and the identity of the client are shown in the following message. The client's security identifier (SID) is included as binary data: %1%0
ID_W_NOT_USER | 0x2001 | An unauthorized client attempted to gain access to an existing instance of an XLANG schedule. The remainder of the moniker string identifying the instance and the identity of the client are shown in the following message. The client's security identifier (SID) is included as binary data: %1%0
ID_W_REHYDRATIONERROR | 0x2002 | An error was encountered while rehydrating an XLANG schedule. There might be a problem reading the database or a problem with the information stored, or your system might be low on resources. The operation will be retried. Detailed information is provided in the following message.%1%0
IDS_E_COMSVCS_INTERNAL_ERROR | 0x3000 | The XLANG Scheduler Engine has detected an inconsistency in its internal state. Please contact Microsoft Product Support Services to report this error: %1%0
IDS_COMSVCS_RESOURCE_ERROR | 0x3001 | The XLANG Scheduler Engine has detected the absence of a critical resource and has caused the process that hosted it to end: %1%0
IDS_COMSVCS_INTERNAL_ERROR_ASSERT | 0x3002 | COM+ internal error. Please contact Microsoft Product Support Services to report this error. Assertion failure: %1%0
ID_E_USER_EXCEPTION | 0x3003 | The system has called a scheduled component and that component has failed and generated an exception. This indicates a problem with the scheduled component. Notify the developer of this component that a failure has occurred and provide the following information: %1%2%0
ID_INITIALIZE_FOR_DTC | 0x3004 | The XLANG Scheduler Engine was unable to initialize for transactions that are required to support transactional components. Make sure that MS DTC is running: %1%0
ID_E_CANT_CREATE_COMPONENT | 0x3005 | The XLANG Scheduler Engine was unable to create a user component that is required by the running XLANG schedule. Detailed information is provided in the following message. %1%0
ID_E_PROGID_NOT_FOUND | 0x3006 | The XLANG Scheduler Engine was unable to convert the Programmatic ID in the following message to a COM class ID: %1%0
ID_E_CANT_CREATE_INTERCEPTOR | 0x3007 | The XLANG Scheduler Engine was unable to create an interceptor object for the interface ID shown in the following message. Probable causes for this are 1) the interface isn't registered properly; 2) no type library is provided for the interface; or 3) the file that contains the interface type information can't be loaded. The port name associated with this interceptor is: %1%0
ID_E_INTF_NOT_SUPPORTED | 0x3008 | The XLANG Scheduler Engine detected an inconsistency between the port implementation and the COM components to which it refers. A component listed in the port implementation has failed to support the expected interface. The class ID of the component and the IID that it failed to support are shown in the following message. The port name associated with this component is: %1%0
ID_E_UNKNOWN_METHOD | 0x3009 | The XLANG Scheduler Engine received a call to a method that was not specified in the port implementation for this XLANG schedule. The IID and method number are shown in the following message. The name of the port on which the call arrived is: %1%0
ID_E_UNKNOWN_IDISPATCH_METHOD | 0x300A | The XLANG Scheduler Engine received a call through the IDispatch::Invoke() interface to a method that no longer exists. The dispatch ID for the method is shown in the following message. The name of the port on which the call arrived is: %1%0
ID_E_NAMED_PARAMS | 0x300B | The XLANG Scheduler Engine received a call through the IDispatch::Invoke() interface to a method that contains named arguments. Use positional arguments instead. The dispatch ID for the method is shown in the following message. The name of the port on which the call arrived is: %1%0
ID_E_BAD_INVOKE_PARAMS | 0x300C | The XLANG Scheduler Engine received a call through the IDispatch::Invoke() interface to a method with an incorrect number of parameters. The IID and the dispatch ID for the method are shown in the following message. The name of the port on which the call arrived is: %1%0
ID_E_BAD_RETURN_POINTER | 0x300D | The XLANG Scheduler Engine received an incorrect Out parameter through the IDispatch::Invoke() interface from a method. The reference returned was either not valid (NULL or a bad pointer) or does not support the expected interface. The expected dispatch ID is shown in the following message. The name of the message containing the bad port reference is: %1%0
ID_E_ACCESS_CHECK_FAILURE | 0x300E | The XLANG Scheduler Engine was not able to authorize the client's moniker resolution request. Access is denied.%0
ID_E_BAD_INVOKE | 0x300F | The IDispatch::Invoke() interface call to a method failed. The dispatch ID for the method is shown in the following message. The name of the port on which the call was attempted is: %1%0
ID_E_INVOKED_METHOD | 0x3010 | The invoked method, whose dispatch ID is shown in the following message, reported an error. The name of the port on which the call was attempted is: %1%0
ID_E_CANT_GET_TYPEINFO | 0x3011 | The component whose port name and COM CLSID are shown in the following message was unable to supply required type information to the XLANG Scheduler Engine.%1%0
ID_E_CANT_INVOKE_METHOD | 0x3012 | The XLANG Scheduler Engine was unable to deliver a method call to the object associated with the port name shown in the following message. The interface and method name that are invoked are also shown.%1%0
ID_E_CANT_GET_CLASSINFO | 0x3013 | The component whose port name and COM CLSID are shown in the following message was unable to supply required type information to the XLANG Scheduler Engine through the IProvideClassInfo::GetClassInfo interface.%1%0
ID_E_SCRIPT_ERROR | 0x3014 | A scripted decision rule in an XLANG schedule instance could not be executed. The error returned by the script engine is shown in the following message. The script's source code and information about the schedule instance in which the error occurred is also provided.%1%0
ID_E_SCRIPT_ERROR_NOINFO | 0x3015 | A scripted decision rule in an XLANG schedule instance has failed. Detailed information regarding the error could not be obtained due to an internal error. The error code is shown in the following message.%1%0
ID_E_SCRIPT_BADCONV | 0x3016 | A scripted decision rule in an XLANG schedule instance referred to a message field whose type was incompatible with the VBScript Engine. The XLANG Scheduler Engine attempted to convert the field to a compatible type but was unable to do so. The information in the following message shows the script rule, message, and field involved, as well as the original field variant type and the type to which a conversion was attempted. The field's VARIANT data structure is attached to this log entry as binary data.%1%0
ID_E_SCRIPT_BADARRAY | 0x3017 | A scripted decision rule in an XLANG schedule instance referred to a message field containing an array type that is incompatible with the VB script engine. Only variant arrays are supported by Visual Basic Scripting. The information in the following message shows the script rule, message, and field involved. The field's VARIANT data structure is attached to this log entry as binary data.%1%0
ID_E_SCRIPT_BADEXPR | 0x3018 | A scripted decision rule in an XLANG schedule instance contained an expression that did not return a Boolean result. The information in the following message shows the script rule and expression involved. The VARIANT data structure returned by the expression is attached to this log entry as binary data.%1%0
ID_E_SCHEDULE_NOT_RUNNING | 0x3019 | The XLANG Scheduler Engine received a call to an object associated with a port in an XLANG schedule instance that is not running. The name of the port on which the call arrived is: %1%0
ID_E_INTERNAL_EXCEPTION | 0x301A | A COM+ internal exception occurred. Contact Microsoft Product Support Services to report this error, and provide them with the information in the following message.%1%2%0
ID_E_BAD_DATAFLOW_NOMESSAGE | 0x301B | There is a problem with the data-flow specification. A message that is indicated as a source of data does not currently exist while this XLANG schedule is running. Detailed information is provided in the following message.%1%0
ID_E_BAD_ARGUMENTVALUE | 0x301C | One of the fields that is used as a parameter for a COM method call has a bad value type in it. This is most likely caused by incorrect or missing data flow. Detailed information is provided in the following message.%1%0
ID_E_DEEP_VARIANT_NESTING | 0x301D | One of the fields that is used as a parameter for a COM method call has more than one nesting level of VARIANTs. The IID and the method's dispatch ID are shown in the following message. The name of the port on which the call arrived is: %1%0
ID_E_BAD_MAPPORTVALUE | 0x301E | A field carrying a mapped port is not valid. Detailed information is provided in the following message.%1%0
ID_E_BAD_CALLPARAMNUMBER | 0x301F | An incorrect number of parameters are being passed into a call. Detailed information is provided in the following message.%1%0
ID_E_EXECUTINGCALLEDSCHEDULE | 0x3020 | The XLANG schedule cannot be executed as a top-level schedule. Context parameters must be passed to it. Detailed information is provided in the following message.%1%0
ID_E_CANT_GET_SUPPORTERRORINFO | 0x3021 | The component whose port name and COM CLSID are shown in the following message was unable to return success from an interface that it claimed to support to the XLANG Scheduler Engine via ISupportErrorInfo::InterfaceSupportsErrorInfo.%1%0
ID_E_PERSIST_FAILURE | 0x3022 | The state of the schedule instance could not be saved to the database. Detailed information is provided in the following message.%1%0
ID_E_TRANSACTION_COMMIT_FAILURE | 0x3023 | The system failed to commit a transactional context. Detailed information is provided in the following message.%1%0
ID_E_TRANSACTION_ABORTED | 0x3024 | The system aborted a transactional context. Detailed information is provided in the following message.%1%0
ID_E_TRANSACTION_ABORT_FAILURE | 0x3025 | The system failed to abort a transactional context. The state of this transaction is not known. Detailed information is provided in the following message.%1%0
ID_E_PENDINGREHYDRATIONERROR | 0x3026 | The rehydration application encountered an error and is shutting down. Some of the rehydration requests will fail due to this shutdown. Restart the XLANG Scheduler Engine service. Detailed information is provided in the following message.%1%0
ID_E_REHYDRATIONONSTARTUPERROR | 0x3027 | One or more XLANG schedules could not be rehydrated because of a system error. There might be problems reading the database or problems with the data that was read. Detailed information is provided in the following message.%1%0
ID_E_REHYDRATIONERROR | 0x3028 | An error was encountered while rehydrating an XLANG schedule. There might be a problem reading the database, or there might be a problem with the information stored. It is probable that the XLANG schedule was not dehydrated properly. Detailed information is provided in the following message.%1%0
ID_E_FOUNDINITIALIZEDTHREAD | 0x3029 | The XLANG Scheduler Engine service encountered a critical thread-management error while processing an XLANG schedule. The schedule might fail to continue processing. Contact your technical support.%1%0
ID_E_CALLONCOMPLETEDSCHEDULE | 0x302A | The XLANG Scheduler Engine service received a call on a completed XLANG schedule instance. The schedule instance has already been removed from memory. The IID for the interface is shown in the following message.%1%0
IDS_MSG_TIMEBOMB_EXPIRED | 0x302B | Thank you for evaluating Microsoft BizTalk Server 2002. The period for this evaluation version has ended. Please contact Microsoft or your software reseller to obtain a licensed version of Microsoft BizTalk Server 2002.%0
ID_E_FIELDPORTPERSISTENCEERROR | 0x302C | An error was encountered while attempting to persist an XLANG schedule instance. Detailed information is provided in the following message.%1%0
ID_E_FIELDPORTREHYDRATIONERROR | 0x302D | An error was encountered while attempting to restore a particular sub-component of an XLANG schedule instance from the database. Detailed information is provided in the following message.%1%0
ID_E_SCHEDULEDONE | 0x3030 | The XLANG Scheduler Engine encountered an error while marking the XLANG schedule instance as done. Either the database could not be updated or another error was encountered in the final stage. Detailed information is provided in the following message.%1%0
ID_E_COMPONENT_INCOMPATIBLE_TXN | 0x3031 | The XLANG Scheduler Engine encountered an error while attempting to instantiate a component. Either the component was previously enrolled in a different transaction, or the component was previously not enrolled in a transaction and the current instantiation requires a transaction. Detailed information is provided in the following message.%1%0
ID_E_SUSPEND_FAILURE | 0x3032 | The XLANG schedule instance could not be suspended. Detailed information is provided in the following message.%1%0
ID_E_INITNEW | 0x3033 | The XLANG Scheduler Engine received an error when doing IPersistStreamInit::InitNew. The class ID of the component and the error code are shown in the following message. The port name associated with this component is: %1%0
ID_E_POSSIBLEBYOTISSUE | 0x3034 | The component you requested could not be created. One possible reason for this is that you have configured the BYOT component inside a COM+ application on this machine. This setting is incompatible with the XLANG Scheduler service. The port name associated with this component is: %1%0
ID_E_FIELDPROCESSINGERROR | 0x3035 | The field value provided was not valid. Detailed information is provided in the following message.%1%0
ID_E_NO_OBJECT | 0x3036 | The XLANG schedule could not be instantiated. Detailed information is provided in the following message.%1%0
ID_E_STARTUP_FAILED | 0x3037 | One or more of the XLANG Group Managers failed to start up with the following error: %1%0
ID_E_NON_SCRIPT_BADEXPR | 0x3038 | An XLANG schedule instance has a rule comparing fields for data types that are not permitted. Detailed information is provided in the following message.%1%0
E_BTW_PERSIST_REACHEDEOF | 0x3039 | The recordset cannot return this row, because the end-of-file (EOF) has been reached.%1%0
ID_E_BAD_DATAFLOW_EMPTYFIELD | 0x3040 | There is a problem with the data-flow specification. A field indicated as a source of data is empty. This may be because it could not be persisted earlier. Detailed information is provided in the following message.%1%0
ID_E_CANT_OPEN_DEADLETTER_QUEUE | 0x3041 | The XLANG Scheduler Engine was unable to create or open the XLANG dead-letter queue for its host COM+ application. The name of the failing COM+ application is: %1%0
ID_E_CANT_XFER_TO_DEADLETTER_QUEUE | 0x3042 | The XLANG Scheduler Engine was unable to transfer an invalid message to the XLANG dead-letter queue for its host COM+ application. The name of the failing COM+ application is: %1%0
ID_E_CANT_LOADMODULE | 0x3043 | The XLANG Scheduler engine was unable to load a required module. This may have been due to compilation/semantic errors with the module. Detailed information is available in the following message: %1%0
ID_E_USER_DATA_EXCEPTION | 0x3044 | A value that was received from the client has caused an exception to be raised. This can be caused by incorrectly allocating memory for the data, by a reference counting mismatch, or other data corruption. The most likely source of the problem is in the client code. Detailed information is available in the following message: %1%2%0
E_BTW_INTERNAL_ERROR | 0x4001 | An internal error has occurred. %1%0
E_EXPORT_FAILED | 0x4002 | The XLANG schedule could not be processed.%0
E_BTW_UNKNOWN_SHAPE | 0x4003 | The compiler does not understand the shape. This shape is an unknown shape.%0
E_BTW_INCOMPLETE_FLOW | 0x4004 | The flow is incomplete because a connector is missing.%0
E_BTW_INCOMPLETE_FLOW_LEFT | 0x4005 | The flow is incomplete. The shape must have a flow connected to the left connector.%0
E_BTW_INCOMPLETE_FLOW_RIGHT | 0x4006 | The flow is incomplete. The shape must have a flow connected to the right connector.%0
E_BTW_INCOMPLETE_FLOW_LATERAL | 0x4007 | The flow is incomplete. The shape is not attached to anything on the side.%0
E_BTW_INCOMPLETE_FLOW_TOP | 0x4008 | The flow is incomplete. The shape must have a flow connected to the top connector.%0
E_BTW_INCOMPLETE_FLOW_BOTTOM | 0x4009 | The flow is incomplete. The shape must have a flow connected from the bottom connector.%0
E_BTW_INCOMPLETE_FLOW_ANYLINE | 0x400A | The flow is incomplete. Not connected to any shape.%0
E_BTW_MIRRORLIST_INCONSISTENT | 0x400B | Mirror shapes are not found in the On Failure or Compensation page. Retry after replacing the shape with a new one.%0
E_BTW_BEGIN_INSIDE_TRANSACTION | 0x4010 | The Begin shape must not be enclosed within a transaction.%0
E_BTW_END_MULTIPLE_LOOP | 0x4020 | Only one End shape can be used in the loop branch.%0
E_BTW_END_IN_TRANSACTION | 0x4021 | The End shape cannot be used in the context.%0
E_BTW_SYNCACTION_NO_PAIR | 0x4030 | Binding to a COM port requires actions to appear in pairs.%0
E_BTW_INCOMPLETE_FLOW_BINDING | 0x4031 | No binding for this action or port.%0
E_BTW_FIELD_TYPE_NOT_SUPPORTED | 0x4040 | Type (variant type=%1) is not supported.%0
E_BTW_ROLE_NOT_SUPPORTED | 0x4050 | Contracts (XLANG Schedules with Roles) cannot be compiled.%0
E_BTW_EMPTY_TRANSACTION | 0x4060 | The transaction contains no valid shapes.%0
E_BTW_TRANSACTION_NOT_PERMITTED | 0x4061 | Transaction shapes are not permitted when the XLANG schedule is treated as a COM+ component. Remove the transaction or edit the properties of the Begin shape to change the transaction model.%0
E_BTW_TRANSACTION_BOUNDARIES_CROSSED | 0x4062 | You cannot connect a flow from outside a transaction to a shape within a transaction without first connecting the flow to the transaction. Draw your flow to the top connection point of a transaction to connect it to the transaction. Then, click the transaction to highlight it. Draw another flow from the transaction connection point to the first shape within the transaction. To draw a flow that leaves the transaction, you must first connect the flow to the connection point at the bottom of the transaction. Then, click the transaction to highlight it. Draw another flow from the bottom connection point to the next shape in the business process.%0
E_BTW_TRANSACTION_TERMINATED_PREMATURELY | 0x4063 | At least one path within the transaction should flow out of the transaction.%0
E_BTW_NO_RULES_FOR_SWITCH | 0x4070 | Decision shapes must contain at least one rule.%0
E_BTW_CANNOT_WAIT_ON_ALL_SWITCH_BRANCHES | 0x40A0 | Cannot wait on "all" branches from the decision.%0
E_BTW_NO_BRANCH_FOUND | 0x40A1 | The join cannot find the corresponding fork or decision.%0
E_BTW_JOIN_MISMATCH | 0x40A2 | Only a single join may be used with a given fork or decision.%0
E_BTW_JOIN_SHARED | 0x40A3 | The same join cannot be used for flows coming from different forks or decisions.%0
E_BTW_CANNOT_WAIT_ON_SOME_SWITCH_BRANCHES | 0x40A4 | Not all paths from the decision come to the join.%0
E_BTW_CANNOT_WAIT_ANY_ON_FORK_BRANCHES | 0x40A5 | Cannot wait "Or". The branches contain process forms that might never finish, resulting in hung schedules.%0
E_BTW_DATAFLOW_DISALLOWED_ON_BTM_PORT | 0x40C0 | This port cannot be used in multiple receive actions or within a single receive action in a loop.%0
E_BTW_MESSAGE_TECH_NOT_FOUND | 0x4110 | The message is not bound to any port.%0
E_BTW_MESSAGE_TYPE_MISMATCH | 0x4111 | The message was used with conflicting types "%1" and "%2".%0
E_BTW_MISSING_TECHNOLOGY | 0x4120 | The list of available methods for this communication flow has changed. Re-run the Method Communication Wizard to select a different method and update this communication flow.%0
E_BTW_MISSING_PORT_DATAFLOW | 0x41A0 | The settings for this port indicate that it is created externally to the XLANG Scheduler Engine. You must designate the source of this port reference by drawing a connection from the appropriate message field.%0
E_BTW_CIRCULAR_DATAFLOW | 0x41A1 | There appears to be a circular path in the data-flow path for this XLANG schedule.%0
E_BTW_LOOP_NORULE | 0x41D0 | A rule has not been defined.%0
E_BTW_LOOP_BODY_EXITS_TRANSACTION | 0x41D1 | The body of the loop cannot exit the enclosing transaction.%0
E_BTW_LOOP_BODY_END_MISSING | 0x41D2 | The end of the body of the loop is not found.%0
E_BTW_ABORT_NOT_IN_TXN | 0x41E0 | Abort shapes must be associated with an enclosing transaction.%0
E_BTW_ABORT_CONTEXT_INVALID_SCOPE | 0x41E1 | Abort shapes can refer to current or parent contexts only.%0
E_BTW_END_MULTIPLE_ABORT | 0x41E2 | Multiple End shapes are not allowed on the On Failure page.%0
E_BTW_COMPILER_FAILED | 0x5000 | Compile failed on "%1".%0
E_BTW_PARSE_FAILED | 0x5001 | Parse failed.%0
E_BTW_FIXUP_FAILED | 0x5002 | Fixup failed.%0
E_BTW_VALIDATION_FAILED | 0x5003 | Validation failed.%0
E_BTW_NODE_FAILURE | 0x5004 | at node "%1" (%2!d!,%3!d!).%0
E_BTW_STACK_TOO_MANY_ITEMS | 0x5005 | Too many items were found on the stack.%0
E_BTW_STACK_UNEXPECTED_NODE | 0x5006 | An unexpected node was found.%0
E_BTW_XMLQUERY_RETURNED_ZERO_NODES | 0x5007 | The XML Query returned zero nodes.%0
E_BTW_XMLQUERY_RETURNED_MULTIPLE_NODES | 0x5008 | The XML Query returned multiple nodes.%1%0
E_BTW_XMLQUERY_MISSING_ATTRIBUTE | 0x5009 | Required attribute "%1" is missing its value.%0
E_BTW_LOAD_MODULE_FAILED | 0x500A | Failed to load module "%1".%0
E_BTW_XML_LOAD_FAILED | 0x500B | The XML-DOM returned an error at "%1!d!, %2!d!".%0
E_BTW_ERROR_LOADING_PACKAGE | 0x500C | 0x%1!X! error occurred while trying to load the following URL: "%2".%0
E_BTW_NAMED_LIST_HAS_DUPLICATE_ENTRIES | 0x500D | The list has duplicate entries with the name "%1".%0
E_BTW_REQUIRED_ELEMENT_MISSING | 0x500E | Required element "%1" is missing.%0
E_BTW_ELEMENT_MISSING_VALUE | 0x5100 | The element value is missing.%0
E_BTW_REFERENCE_RESOLVE_FAILED | 0x5110 | Unable to resolve "%1" with location value "%2".%0
E_BTW_CONTEXTREF_INVALID_REFERENCE | 0x5120 | Returning to or "releasing" from an independent (non-enclosing) context is not permitted.%0
E_BTW_CONTEXTREF_SELF_REFERENCE | 0x5121 | Return or Release referring to a context from within that context is not permitted.%0
E_BTW_ASYNC_ACTION_COM_NOT_ALLOWED | 0x5400 | An asynchronous action must refer to a non-COM port.%0
E_BTW_CONNECTION_PORT_HAS_TECH_BINDING | 0x5490 | The port "%1" used in a connection cannot have technology binding.%0
E_BTW_CONNECTION_PORT_REUSED | 0x5491 | The port "%1" used in a connection has been used before in the XLANG schedule.%0
E_BTW_TRANSACTIONS_NESTED | 0x54B0 | When transactions are nested, the outer transaction must be long-running.%0
E_BTW_TRANSACTIONS_NESTED_RETRY | 0x54B1 | When transactions are nested, the outer transaction cannot have retry count.%0
E_BTW_MESSAGE_HAS_NO_DECL | 0x5520 | Message "%1" has no associated declaration.%0
E_BTW_MESSAGE_HAS_UNSATISFIED_DATA_DEPENDENCIES | 0x5521 | Message "%1" has unsatisfied data dependencies on "%2". The dependencies are either not getting created in the flow or are potentially expected on a port in which the "No instantiation" option has been selected.%0
E_BTW_PORT_HAS_NO_BINDING | 0x5570 | Port "%1" has no associated binding.%0
E_BTW_PORT_HAS_UNSATISFIED_DATA_DEPENDENCIES | 0x5571 | Port "%1" has unsatisfied data dependencies on messages "%2". The dependencies are either not being created in the flow or are potentially expected on a port in which the "No instantiation" option has been selected.%0
E_BTW_RULE_HAS_NO_BINDING | 0x55B0 | Rule "%1" has no associated binding.%0
E_BTW_SCHEDULE_SUSPENDED | 0x55E0 | The XLANG schedule has been suspended.%0
E_BTW_SCHEDULE_STOPPED | 0x55E1 | The XLANG schedule has been stopped.%0
E_BTW_PERSIST_FAILED | 0x55E2 | The state of the XLANG schedule instance could not be saved to the database.%0
E_BTW_SUSPEND_FAILED | 0x55E3 | The XLANG schedule could not be suspended.%0
E_XLANG_SHUTTINGDOWN | 0x55E4 | The XLANG application is shutting down.%0
E_BTW_MISSING_MESSAGE_BINDING_ON_PORT | 0x5730 | The action uses port "%1" whose binding does not define the binding for message "%2".%0
E_BTW_MISSING_INCOMING_PORTREF | 0x5731 | The message used by this receive action contains a field (%1) that is connected to a port reference (%2) but the dataflow connections do not indicate that the port reference should be received.%0
E_BTW_SOURCE_PORT_HAS_NOINVOCATION | 0x5740 | The send action refers to port "%1", in which the "No instantiation" option has been selected.%0
E_BTW_MISSING_OUTGOING_PORTREF | 0x5741 | The message used by this source action contains a field (%1) that is connected to a port reference (%2) but the dataflow connections do not indicate that the port reference should be sent.%0
E_BTW_TASK_LIMIT | 0x5750 | The task has "%1!d!" actions. The current limit is "%2!d!".%0
E_BTW_SYNC_DIFFERENT_PORTS | 0x5760 | Synchronous action pair refers to different ports: "%1" and "%2".%0
E_BTW_SYNC_SAME_MESSAGE | 0x5761 | Synchronous action pair refers to the same message: "%1".%0
E_BTW_SYNC_ONLY_COM_ALLOWED | 0x5762 | Synchronous action pair must refer to COM port only.%0
E_BTW_SYNC_SECOND_MESSAGE_MUST_BE_OUT_FOR_FIRST_MESSAGE | 0x5763 | In a synchronous action pair the message in the second action must be the out message for the message in the first action.%0
E_BTW_INVALID_DELAY_TIME | 0x5770 | The delay time (%1!d!) is not valid. The delay time cannot be a negative number.%0
E_BTW_CALL_MESSAGE_SCHEMA_NAME_MISMATCH | 0x5800 | The message specification name "%1" for the message "%2" in the calling XLANG schedule does not match the specification name "%3" in the called XLANG schedule.%0
E_BTW_CALL_MESSAGE_SCHEMA_REPRESENTATION_MISMATCH | 0x5801 | The message specification representation for message "%1" in the calling XLANG schedule does not match the specification representation in the called XLANG schedule.%0
E_BTW_ASSIGNMENT_PORT_HAS_TECH_BINDING | 0x5830 | Port "%1" used in an assignment in a cut form cannot have technology binding.%0
E_BTW_PARTITION_LIMIT | 0x5850 | The partition has "%1!d!" process(es). The current limit is "%2!d!".%0
E_BTW_MESSAGE_USED_IN_PARALLEL | 0x5851 | Parallel actions or processes use the same message "%1".%0
E_BTW_PORT_USED_IN_PARALLEL | 0x5852 | Parallel actions or processes use the same port "%1".%0
E_BTW_INVALID_RETRY_COUNT | 0x5A30 | The retry count "%1!d!" is not valid. The retry count cannot be negative.%0
E_BTW_INVALID_BACKOFF_VALUE | 0x5A31 | The back-off value "%1!d!" is not valid. The back-off value cannot be negative.%0
E_BTW_INVALID_TIMEOUT_VALUE | 0x5A32 | The timeout value "%1!d!" is not valid. The timeout value cannot be negative.%0
E_BTW_FIELD_RESERVED_NAME | 0x5A50 | %1 is a reserved field name.%0
E_BTW_ELEMENT_TYPE_NOT_DEFINED | 0x5A51 | The element type "%1" is not defined.%0
E_BTW_ELEMENT_TYPE_INCOMPLETE | 0x5A70 | The element type definition is incomplete. Provide either subelements or dt:type.%0
E_BTW_MULTIPLE_PORTS | 0x5A90 | Distinct ports "%1" and "%2" are used on the same field.%0
E_XLANG_INVALID_COMPARE_TYPE | 0x5A91 | Comparison of this data type is not permitted.%0
E_BTW_FIELD_NOT_MATCHING_SCHEMA_ELEMENT | 0x5A92 | FieldBinding for "%1" does not have a matching element in the schema at position "%2!d!".%0
E_BTW_FIELD_HAS_AMBIGUOUS_DATAFLOW | 0x5A93 | A message field cannot have both a data flow from another message field and a reference to a port. One of the data flows must be removed.%0
E_BTW_PORT_TARGET_INVALID | 0x5A94 | The type of this field is inappropriate for use as a port reference. Ports bound to a COM component can be communicated as object references or strings. Ports bound to Message Queuing may only be transferred as strings. Internal ports can be communicated only as object references.%0
E_BTW_FIELD_TARGET_INVALID | 0x5A95 | The target field "%1", which is of variant type "%2", cannot get data from source field "%3", which is of variant type "%4".%0
E_BTW_INITIALIZED_MESSAGEFIELD_INVALID_OVERWRITE | 0x5A96 | The data in field "%1" of an initialized message "%2" cannot be overwritten with data from another message or port in the binding specification.%0
E_BTW_DATAFLOW_INCOMPLETE | 0x5AB1 | A source action accepting [in] parameters must have the corresponding fields populated by data flow (that is, "from").%0
E_BTW_DATAFLOW_FROM_SYSTEM_FIELD | 0x5AB2 | Port cannot be initialized from a system field.%0
E_BTW_DATAFLOW_FROM_CONSTANT_FIELD | 0x5AB3 | Port cannot be initialized from a constant message field.%0
E_BTW_MISSING_SCRIPT_EXPRESSION | 0x5AC0 | No script expression was supplied for the rule.%0
E_BTW_BAD_SCRIPT_EXPRESSION | 0x5AC1 | %1 %2 at character position %3!d! in "%4".%0
E_BTW_MAP_INVALID_BINDING | 0x5AE0 | The binding for message "%1" must contain a reference for mapped port "%2".%0
E_BTW_MESSAGE_BINDING_SCHEMA_MISMATCH | 0x5AE1 | There is a mismatch between the binding and schema for the message "%1".%0
E_BTW_MESSAGEDECL_INIT_DATA_UNAVAILABLE | 0x5B00 | Unable to obtain initialization data for field "%1".%0
E_BTW_LATENCY_INVALID_VALUE | 0x5B20 | The Latency property value must be a non-negative integer that is less than the maximum long integer "%1!d!".%0
E_BTW_PORT_LATENCY_ON_INTERNAL | 0x5B21 | Cannot specify latency on an internal port.%0
E_BTW_MESSAGE_TECHNOLOGY_MISMATCH | 0x5BB0 | There is a mismatch between the port "%1" technology "%2" and the message "%3" technology "%4".%0
E_BTW_FIELD_TECHNOLOGY_MISMATCH | 0x5BC0 | There is a mismatch between the message "%1" technology "%2" and the field "%3" technology "%4".%0
E_BTW_COM_PORT_NOT_CREATABLE | 0x5C10 | If a COM port can be invoked, it must have a CLSID, a ProgID, or a moniker.%0
E_BTW_AUTORETURN_COM_PORT_MUST_BE_USED_INSIDE_CONTEXT | 0x5C11 | The port "%1", which is configured to abort a transaction if a method returns a failure HRESULT, can only be used inside a transaction.%0
E_BTW_COM_PORT_GENERAL_ACCESS_FAILURE | 0x5C12 | A COM port can be invoked. Please refer to the Windows 2000 documentation.%1%0
E_BTW_COM_PARAMETERS_LIMIT | 0x5C20 | The method has "%1!d!" parameter(s). The current limit is "%2!d!".%0
E_BTW_COM_NO_MATCHING_RETURN | 0x5C21 | The COM method has no matching Return.%0
E_BTW_COM_NO_MATCHING_METHOD | 0x5C22 | The COM Return has no matching method.%0
E_BTW_INVALID_SLOT_NUMBER | 0x5C23 | The slot number "%1!d!" is not valid. Slot numbers cannot be less than the following value: SLOT_NONE(-1).%0
E_BTW_INVALID_INVOKE_KIND | 0x5C24 | The invokeKind value "%1!d!" is not valid. Acceptable values are: 1,2,3,4 and 8.%0
E_BTW_PROXY_DISCONNECTED | 0x5C25 | The proxy has been disconnected.%0
E_BTW_COM_DISPATCH_SLOT_SPECIFIED | 0x5C26 | A slot number cannot be specified for the dispatch interface.%0
E_BTW_COM_SPECIFY_DISPID_OR_SLOT | 0x5C27 | Valid values for dispid or slot must be specified.%0
E_BTW_COM_INVALID_BYREF_FOR_RETURN_MESSAGES | 0x5C30 | Byref should be "1" since "%1" is a <com:return> message.%0
E_BTW_COM_INVALID_NESTED_VARIANTS | 0x5C31 | More than one level of nesting for variants is not permitted.%0
E_BTW_COM_FIELD_INDEX_MUST_BE_NON_NEGATIVE | 0x5C32 | The index "%1!d!" for the field is not valid. The index must be a non-negative integer.%0
E_BTW_COM_FIELD_INDEX_REPEATED | 0x5C33 | The index "%1!d!" for the field has been used before on another field in the message.%0
E_BTW_COM_FIELD_INDEX_NOT_CONTIGUOUS | 0x5C34 | For synchronous action pair messages "%1" and "%2", the index "%3!d!" for a field is not valid. The field indices for these messages must form a contiguous block of non-negative numbers that start with zero.%0
E_BTW_MSMQ_NO_MQRT_DLL | 0x5D00 | The Message Queue DLL, MQRT.DLL, cannot be loaded.%0
E_BTW_MSMQ_CREATECHANNEL | 0x5D01 | MQBinder: CreateChannel failed for: %1.%0
E_BTW_MSMQ_NOT_CONFIGERED_PROPERLY | 0x5D02 | The Message Queuing Service is not configured properly. A queue object could not be opened %1.%0
E_BTW_MSMQ_NO_CERTIFICATE_AVAILABLE | 0x5D03 | The Message Queuing Service is not able to obtain a certificate.%1%0
E_BTW_MSMQ_NO_WELLKNOWN_QUEUE_NAME | 0x5D04 | A message cannot be sent to a known queue because the queue is not named in the XLANG schedule. You must provide a queue name in the XLANG schedule.%1%0
E_BTW_MSMQ_INVALID_FIELD_TYPE | 0x5D05 | The field type specified for message "%1" field "%2" is not valid.%0
E_BTW_MSMQ_PORT_NOT_BOUND | 0x5D06 | The Message Queuing port is not bound.%1%0
E_BTW_MSMQ_QUEUE_NOT_TRANSACTIONAL | 0x5D10 | The queue does not have the correct transactional properties.%1%0
E_BTW_MSMQ_OPEN_ACCESSDENIED | 0x5D11 | A Message Queuing access denied error occurred when opening the queue. Compare the accessRole specified for the queue in the XLANG schedule with the rights associated to the current user.%1%0
E_BTW_MSMQ_OPEN_GENERALFAILURE | 0x5D12 | A Message Queuing failure occurred when opening the queue. Refer to the Message Queuing Service documentation in Windows 2000 to look up the error code and diagnose as appropriate.%1%0
E_BTW_MSMQ_PORT_NOT_CREATABLE | 0x5D13 | A port that is implemented by using a message queue must have a queue name.%0
E_BTW_MSMQ_GENERAL_QUEUE_ACCESS_FAILURE | 0x5D14 | A Message Queuing failure occurred when accessing the queue. Refer to the Message Queuing Service documentation in Windows 2000 to look up the error code and diagnose as appropriate.%1%0
E_BTW_MSMQ_INVALID_MESSAGE_VT_TYPE | 0x5D20 | The Message Queuing message is of unknown format.%1%0
E_BTW_MSMQ_MESSAGE_UNKNOWN_MESSAGETYPE | 0x5D21 | The Message Queuing message is of unknown message type. The message type could not be obtained from the message.%1%0
E_BTW_MSMQ_MESSAGE_UNAUTHENTICATED | 0x5D22 | The Message Queuing message is not authenticated but the port only accepts authenticated messages.%1%0
E_BTW_MSMQ_MESSAGE_INCORRECT_AUTHENTICATE_LEVEL | 0x5D23 | The Message Queuing message is not authenticated at the requested level.%1%0
E_BTW_MSMQ_MESSAGE_INVALID_MESSAGE | 0x5D24 | The Message Queuing message has a message body that is not valid.%1%0
E_BTW_MSMQ_MESSAGE_NOT_SEND | 0x5D25 | The Message Queuing message could not be sent.%1%0
E_BTW_MSMQ_MESSAGE_SCHEMAVALIDATION_FAILED | 0x5D26 | The Message Queuing message was not successfully validated against the schema that was provided. Check the schema and the schema path.%1%0
E_BTW_MSMQ_COULD_NOT_CREATE_MQMESSAGE | 0x5D27 | The message instance could not be converted to a Message Queuing message. %1%0
E_BTW_MSMQ_NO_TRUSTRELATIONSHIP_FOR_USER | 0x5D28 | The trust relationship for the provided user could not be established.%1%0
E_BTW_MSMQ_MESSAGE_EMPTY_MESSAGE | 0x5D29 | The Message Queuing message has an empty message body.%1%0
E_BTW_MSMQ_MESSAGE_ONLY_ONE_EMPTY_XPATH_ALLOWED | 0x5D2A | The Message Queuing message can have only one field with an empty node path (XPath).%0
E_BTW_MSMQ_MESSAGE_ONE_EMPTY_XPATH_NEEDED | 0x5D2B | The Message Queuing message must have one field with an empty node path (XPath).%0
E_BTW_MSMQ_MESSAGE_INVALID_MESSAGEBODY | 0x5D2C | The Message Queuing message has a message body that is not valid.%1%0
E_BTW_MSMQ_MESSAGE_INVALID_MESSAGESTRING | 0x5D2D | The Message Queuing message has an invalid string for the message body.%1%0
E_BTW_MSMQ_MESSAGE_UNKNOWN_MESSAGE | 0x5D2E | The Message Queuing message is an invalid or unknown message and was moved to the dead-letter queue.%1%0
E_BTW_MSMQ_MESSAGE_TYPE_CONFLICTING_SCHEMA | 0x5D2F | The Message Queuing messages "%1" and "%2", which are of type "%3" on port "%4", have conflicting specification representations. This could be because the name, type, or XPath query does not match for one of the fields in the two representations.%0
E_BTW_MSMQ_DOCUMENT_FIELD_TYPE_NOT_STRING | 0x5D30 | A Message Queuing message's field "%1", that has an empty node path (XPath), must be a string data type.%0
E_BTW_MSMQ_DOCUMENT_FIELD_CANNOT_CONVERT_TO_STRING | 0x5D31 | A Message Queuing message's field could not be converted to a string.%1%0
E_BTW_MSMQ_DOCUMENT_FIELD_CONVERTION_FAILURE | 0x5D32 | The Message Queuing message's field could not be converted.%1%0
E_BTW_CANT_DISPOSE_MESSAGE | 0x6001 | The XLANG schedule instance was bound to a queue that received a message that is not valid. The XLANG Scheduler Engine was unable to transfer this message to the dead-letter queue, so the schedule instance has been terminated.%0

Related Topic

Configure Event Viewer for BizTalk Server errors


Standard COM Error Messages

The following table shows the most common standard COM errors returned by the properties and methods of the BizTalk Server objects.

Constant | Value (32-bit) | Description
S_OK | 00000000 | The standard return value used to communicate successful completion.
S_FALSE | 00000001 | An alternate success value, typically used to communicate successful, but non-standard completion. The precise meaning depends on the method or property in question.
E_UNEXPECTED | 8000FFFF | Catastrophic failure error.
E_NOTIMPL | 80004001 | Not implemented error.
E_OUTOFMEMORY | 8007000E | Out of memory error.
E_INVALIDARG | 80070057 | One or more arguments are not valid error.
E_NOINTERFACE | 80004002 | Interface not supported error.
E_POINTER | 80004003 | Pointer not valid error.
E_HANDLE | 80070006 | Handle not valid error.
E_ABORT | 80004004 | Operation aborted error.
E_FAIL | 80004005 | Unspecified error.
E_ACCESSDENIED | 80070005 | General access denied error.
MK_E_NOOBJECT | 800401E5 | The object identified by this moniker could not be found.

Additional information may be available using the global Err object. In Visual Basic, the Description property of the Err object may contain a text description of the error.

In C++, call the OLE DB method GetErrorInfo on the IErrorRecords interface to retrieve the most recently set IErrorInfo pointer in the current logical thread. The GetDescription method of the IErrorInfo interface may return a text description of the error. For more information about the GetErrorInfo method, go to the MSDN Online Library Web site (msdn.microsoft.com/library/default.asp) and browse to OLE DB Interfaces in the Platform SDK.


BizTalk Server Glossary

A

abort

To cancel a transaction that is in progress. In orchestration schedules, the Abort shape is used to explicitly tell the XLANG Scheduler Engine to discontinue transaction retries and consider the atomic transaction to have failed. Transactions that have failed may optionally run "On Failure of Transaction" code.

See also: transaction, commit

action

To send or receive a message. Send or receive actions can be synchronous or asynchronous, depending upon which application services are implemented in an XLANG schedule.

advanced query

An expression used to locate specific information. In BizTalk Document Tracking, an advanced query is an SQL statement that you use to extract specific tracking data from the Tracking database, using custom search criteria, such as a Purchase Order Total.

See also: query

ANSI X12

EDI standards set by Accredited Standards Committee X12, whose work is approved by the American National Standards Institute.

Application Center 2000

A Microsoft product that simplifies the task of migrating applications through the development cycle (from development to testing to production). Application Center helps ensure consistency between a development application, a test application, and a production application. By automating deployment of applications from one server to another, Application Center speeds up transfer time, eliminates manual errors, and improves the quality of releases.

Application Center 2000 cluster

A group of independent servers working together as a unified computing resource. An Application Center cluster does not share resources; rather, it provides high availability by isolating and ignoring failed cluster members. Compare with Microsoft Windows Clustering, which provides high reliability through resource sharing and failover.

application integration component (AIC)

A COM object that the BizTalk Server state engine calls to deliver data to an application. If a messaging port is configured in BizTalk Server 2002 to include the use of an AIC for application integration, this component is automatically instantiated and passed the requisite data. The component then determines how to handle communicating this data back to the application. This can be done using private API calls, invoking other COM objects, using database writes, and so on.

asynchronous communication

An interaction between two or more processes in which one process communicates with another and can continue processing independently from the other process.

See also: synchronous communication

attribute

A characteristic of a record or field. An attribute can contain several properties.

B

binding

A process by which the technology used to implement a port is specified.

See also: port

BizTalk Accelerator for HIPAA

An add-on product to Microsoft BizTalk Server 2002 that allows organizations to quickly and easily build HIPAA solutions. BizTalk Accelerator for HIPAA includes several applications that enable health care providers, payers, and clearinghouses (acting on behalf of providers or payers) to exchange, monitor, and control HIPAA-specific transactions. BizTalk Accelerator for HIPAA provides the necessary document specifications, applications, and components to rapidly develop BizTalk Server 2002-based solutions that are HIPAA specific.

BizTalk Document Tracking

A Web-based user interface (UI) that is used to access all BizTalk Messaging Services tracking information. It can also track XLANG schedule status for BizTalk Orchestration Services.

BizTalk Editor

A tool with which you can create, edit, and manage specifications. With BizTalk Editor you can create a specification based on a specification template, an existing schema, certain types of document instances, or a blank specification.

BizTalk Framework

A platform-neutral e-commerce framework that is based on Extensible Markup Language (XML) schemas and industry standards. The framework enables integration across industries and between business systems, regardless of platform, operating system, or underlying technology. Specifically, it is composed of three things: schema, products, and services. For more information about the BizTalk Framework, go to the BizTalk Web site (www.microsoft.com/biztalk/).

BizTalk Mapper

A tool with which you can create maps that define the correspondence between the records and fields in one specification and the records and fields in another specification. A map contains an Extensible Stylesheet Language (XSL) style sheet that is used by BizTalk Server to perform the transformation described in the map.

BizTalk Messaging Management database

A Microsoft SQL Server database that stores the information related to all server configurations, including group and server settings, receive functions, and all messaging configuration information for the objects that are created by using BizTalk Messaging Manager, or by accessing the BizTalk Messaging Configuration object model.

BizTalk Messaging Manager

A graphical user interface (UI) that can be used to configure BizTalk Messaging Services to exchange documents between trading partners and applications of the home organization.

See also: BizTalk Messaging Services

BizTalk Messaging Services

Services that include sending, receiving, parsing, and tracking documents; receipt generation and correlation; and data mapping, integrity, and security.

See also: BizTalk Messaging Manager

BizTalk Orchestration Designer

A design tool used to create drawings that describe long-running, loosely coupled, executable business processes. The XLANG schedule drawing is compiled into an XLANG schedule that is used to execute the automated business process.

BizTalk Orchestration Services

Services that include designing, compiling, and running XLANG schedules. Additional services include the ability to create custom COM+ applications to host dedicated XLANG schedule instances, and the persistence of XLANG schedules.

BizTalk SEED Wizard

A tool that enables a company to create an XML package containing that company's configuration. After the package is created, trading partners can use BizTalk SEED Wizard to install the configuration within their organizations in order to conduct business with the initiating company on the Web.

BizTalk Server 2002

A Microsoft product for business-process automation and application-integration both within and between businesses. BizTalk Server 2002 provides a powerful Web-based development and execution environment that integrates loosely coupled, long-running business processes, both within and between companies.

BizTalk Server 2002 features include the composition of new and existing XLANG schedules; integration among existing applications; the definition of document specifications and specification transformations; and the monitoring and logging of run-time activity.

The server provides a standard gateway for sending and receiving documents across the Internet, as well as providing a range of services that ensure data integrity, delivery, security, and support for the BizTalk Framework and other key document formats.

BizTalk Server Accelerator for RosettaNet

An add-on product to Microsoft BizTalk Server 2002 that allows organizations to quickly and easily build RosettaNet solutions. BizTalk Server Accelerator for RosettaNet includes several applications that enable users to develop, administer, and test RosettaNet standards-compliant Partner Interface Processes (PIPs) implemented as BizTalk Server 2002 XLANG schedules.

BizTalk Server Administration

A Microsoft Management Console (MMC) interface that is used to administer the BizTalk Server 2002 group of servers and their properties, to monitor receive functions, and to monitor work items in the Microsoft SQL Server queues that are used by the server group.

C

channel

A set of properties that designates the source of documents and defines specific processing steps that are performed by BizTalk Messaging Services before a document is delivered to the destination designated by the messaging port or distribution list with which the channel is associated.

See also: pass-through submission, receipt channel, source application, trading partner, open channel, open messaging port, source organization

channel filtering

To compare the value of fields within a document instance to values in expressions designated within a channel. This comparison filters the selection of which channel or channels the server invokes to process a document.

channel ID

A globally unique identifier (GUID) assigned by BizTalk Server 2002 to uniquely identify the channel through which a document is processed.

checkpoint

A storage location in the Shared Queue database in which the current state of a work item is stored. In case of a server failure, documents that were queued to the failed server can be retrieved from the Shared Queue database and redistributed to other servers within the server group, based on the information provided by the checkpoint.

cluster

A group of independent servers managed as a single system for higher availability, easier manageability, and greater scalability. The minimum requirements for a server cluster are: two servers connected by a network, a method for each server to access the other's disk data, and special cluster software like Windows Clustering. The special software provides services such as failure detection, recovery, and the ability to manage the servers as a single system.

code list

A list of code values used as abbreviations for a variety of textual information. For example, ST is the code list value for Ship To and is most commonly used to qualify an address.

commit

To implement all changes requested by a pending transaction. This action occurs when all actions within a transaction are successfully completed.

See also: abort, transaction

Communication shapes

Shapes that are used to identify the exact content of a message and type of application service that is implemented within an XLANG schedule drawing. This category of shapes includes Constants, Message, Port, and Port References.

See also: Flowchart shapes, Implementation shapes, XLANG schedule drawing

compensation

A process by which reparation is made for a completed transaction. For example, if payment has been made for an order that then cannot be fulfilled, the payment is returned to the purchaser.

compile

In BizTalk Mapper, to create an Extensible Stylesheet Language Transformations (XSLT) version of a map that can be used by BizTalk Server. The map is stored in the WebDAV repository and used by BizTalk Server to translate one document format into another document format.

See also: map, data mapping, data translation, Extensible Markup Language (XML)

concurrency

Two or more actions that are carried out at the same time.

configuration

A package of information that defines the various components of BizTalk Server 2002, including resources, such as BizTalk Ports, BizTalk PortGroups, BizTalk Receive Functions, BizTalk Schedules, and BizTalk Custom Counters.

correlation

The association of an incoming document with the correct schedule instance.

correlation token

A variable parameter that is returned to the client upon successful submission to the HTTP receive function. It contains either a submission handle or the file name, depending on whether the document is submitted to BizTalk Server or to a file.

custom counters

Values that enable users to define their own Windows Management Instrumentation (WMI) class instances based on an advanced query of the Tracking database.

cyclical reference

A reference in a specification that occurs when a record is created as a descendant to itself. A cyclical reference can occur only when the Standard property value is set to XML on the Reference tab in BizTalk Editor.

D

data mapping

In BizTalk Mapper, to create a correspondence between the records and fields of a source specification and the records and fields of a destination specification.

See also: compile, data translation

data translation

A process that converts data from one format to another format. Data translation occurs within BizTalk Server at run time. The rules that are specified in a map are used to convert data from a source specification format to a destination specification format, as well as to perform any operations or calculations that are required on the data.

See also: compile, data mapping, map, Extensible Markup Language (XML)

decision

A process that evaluates one or more rules sequentially. In BizTalk Orchestration Designer, a decision is represented by the Decision shape. Rules are Microsoft Visual Basic Scripting Edition (VBScript) expressions that are used by Decision and While shapes.

dehydrate

To store all state information for an XLANG schedule instance in a SQL Server database while the XLANG Scheduler Engine is waiting to receive a message before executing the next action in the business process.

See also: XLANG Scheduler Engine

dehydrated schedule

A schedule that is stored in a database temporarily while waiting for receipt of a message before continuing to the next action in the sequence. All state information about the schedule is stored in the database until the message is received. Dehydrating schedules reduces the load on the computer that is hosting the schedule.

delimited flat file

A file that contains one or more records that are represented as a group of fields separated by a delimiter character. The records themselves are also separated by delimiter characters.

destination

The name of the organization for the channel through which a document is processed. The destination is defined in BizTalk Messaging Services.

destination application

A home-organization application that has been designated in a messaging port as the destination for documents.

See also: home organization

destination organization

A trading partner organization that has been designated in a messaging port as the destination for documents.

See also: openness, organization, source organization

destination specification

The specification in a map that represents the outgoing document. BizTalk Mapper maps from a source specification to a destination specification.

See also: source specification

dictionary

A collection of properties associated with each item of work processed by BizTalk Server. These properties are exposed in BizTalk Editor so that users can tell BizTalk Server how to find values within document instances for properties that are used to locate a messaging port.

distribution list

A group of messaging ports that can be used to send the same document to several different trading partner organizations or applications of the home organization. In the BizTalk Messaging Configuration object model, this is referred to as a port group.

See also: messaging port, trading partner, home organization

document definition

A set of properties that represents a specific document. Document definition properties include a pointer to a document specification and can include global tracking fields and selection criteria.

See also: global tracking fields, selection criteria

document instance

A representation of the actual data that is sent to BizTalk Server. A document instance differs from a specification in that the specification defines the structure of the data, while a document instance is a representation of the specific data contained in a structure.

See also: global tracking fields, pass-through submission

document messaging

Using BizTalk Messaging Services to send, receive, parse and track message documents.

document standard

The structure that defines a transaction set, such as an X12 850 standard. An implementation guideline can be created from a document standard.

document type

A designation for the type of document on which a specification is based. For example, if a specification is based on 850Schema.xml from the X12 standard, when that specification is opened in BizTalk Editor, 850 appears in the document type field on the Reference tab for the root node.

document type definition (DTD)

A standard definition that specifies which elements and attributes might be present in other elements and attributes and that specifies any constraints on their ordering, frequency, and content.

dynamic port

A port that requires that specific location information be provided for an XLANG schedule at run time. The location for a dynamic port is provided by a message that passes the location information to the reference for the port at run time.

See also: static port, port

dynamic queue

A queue that has an unknown address. Ports that use a Message Queuing implementation can use a dynamic queue when the location of the queue is not known. The address of this queue must be provided by a message that passes the queue address to the reference for the port at run time.

See also: static queue, per-instance queue

E

EDIFACT

Electronic Data Interchange For Administration, Commerce, and Transport. The international EDI standard as developed through the United Nations. This standard is commonly used in Europe, as well as Japan and other Asian countries/regions. Also known as UN/EDIFACT.

electronic data interchange (EDI)

A set of standards used to control the transfer of documents, such as purchase orders and invoices, between computers.

See also: selection criteria

element

A set of markup tags that identifies named sections of information. The tags in an element identify the name and the start and end of the element.

enterprise application integration (EAI)

A system that enables separate applications to share data electronically. EAI can help your organization perform integration tasks and individual transactions.

envelope

1. A set of properties that defines an envelope. Envelope properties include an envelope format and can include a pointer to an envelope specification.

2. Header and footer information, or header information only, that encapsulates or precedes document data for transport.

envelope format

The format of documents that an envelope can contain; for example, XML or X12.

event consumer

The recipient of system and application event notifications such as Windows Management Instrumentation (WMI) events and Windows NT Event Log events. For example, Microsoft Operations Manager (MOM) is an event consumer that uses event notifications to raise alerts, notify administrators, and run scripts.

See also: provider

Extensible (XML) Structure Definitions (XSD)

A schema language. The XSD language is the one most recently recommended by the World Wide Web Consortium (W3C) for defining Extensible Markup Language (XML) structures.

Extensible Markup Language (XML)

A specification developed by the World Wide Web Consortium (W3C) that enables designers to create customized tags beyond the capabilities of standard HTML. While HTML uses only predefined tags to describe elements within the page, XML enables tags to be defined by the developer of the page. Tags for virtually any data item, such as a product or an amount due, can be used for specific applications. This enables Web pages to function as database records.

See also: compile, data translation, map, XML-Data Reduced (XDR), XPath

Extensible Stylesheet Language (XSL)

A style sheet format for Extensible Markup Language (XML) documents. XSL is used to define the display of XML in the same way that cascading style sheets (CSS) are used to define the display of Hypertext Markup Language (HTML). BizTalk Server uses XSL as the translation language between two specifications.

F

failfast

The early termination of a process, upon discovery of an internal error or inconsistency, in an effort to avoid a subsequent error or errors that might be serious or unrecoverable.

Flowchart shapes

Shapes that represent the routing logic in an XLANG schedule drawing. This category of shapes includes Abort, Action, Begin, Decision, End, Fork, Join, Transaction, and While.

See also: Flowchart stencil, XLANG schedule drawing, Communication shapes, Implementation shapes

Flowchart stencil

A drawing stencil provided by BizTalk Orchestration Designer. The Flowchart stencil provides all the shapes that can be used to design the process flow of a business process that can be executed by a running XLANG schedule.

See also: Implementation stencil, Flowchart shapes

fully configured rules

Microsoft Operations Manager (MOM) rules that are completely preconfigured as part of the Microsoft BizTalk Server 2002 Management Pack.

See also: user-defined rules

functoid

Built-in reusable function that enables complex structural manipulation operations between source specification elements, destination specification elements, and other functoids.

See also: link

Functoid Palette

A toolbox that contains all functoids that can be used to create relationships between source specification elements and destination specification elements.

G

global tracking fields

Document specification fields, designated in a document definition, that are logged to a tracking database for each instance of an actual document processed by BizTalk Messaging Services.

See also: document definition, document instance

H

Hierarchical Level (HL)

A segment in a hierarchical structure that identifies levels of detail information, such as relating line-item data to shipment data, and packaging data to line-item data. You use HL to identify the dependencies between and the content of hierarchically related groups of data segments.

home organization

An object that represents your business in BizTalk Messaging Manager. The home organization is created for you when BizTalk Server 2002 is installed. Only the home organization can have applications.

See also: destination application, distribution list, organization, source application, trading partner

I

Implementation shapes

Shapes that represent the technologies that the XLANG Scheduler Engine supports. This category of shapes includes BizTalk Messaging, COM Component, Message Queuing, and Script Component.

See also: Flowchart shapes, Implementation stencil, Communication shapes

Implementation stencil

A drawing stencil provided by BizTalk Orchestration Designer. The Implementation stencil provides all the shapes that can be used to bind a port to an implementation technology.

See also: Flowchart stencil, Implementation shapes

implementation technologies

Technologies used to implement a port in an XLANG schedule. The technologies supported by the XLANG Scheduler Engine include COM components, Windows Script Components, Message Queuing Services, and BizTalk Messaging Services.

industry standard

A defined standard that is used for the exchange of information. Standards are extensible, and they follow a well-defined set of rules, or syntax.

initiator

A company that uses BizTalk SEED Wizard to create a SEED package to send to trading partners (recipients) so that they can exchange business documents. A common scenario consists of a single company interacting with several trading partners of the same kind; the central company is called the initiator and the trading partners are called recipients.

See also: SEED package, recipient

inner transaction

A transaction that is contained within the process flow of another transaction.

See also: long-running transaction, nested transaction, outer transaction, transaction

input instance

A content-bearing document that corresponds to a particular schema or specification.

See also: output instance

interchange

A collection of one or more document instances that comprises a single transmission and is exchanged from application to application within an organization or from one trading partner to another.

K

knowledge base

A collection of rule comments that embodies knowledge about the meaning and importance of events. The Microsoft Knowledge Base contains predefined information from Microsoft. The company knowledge base contains information entered by the Microsoft Operations Manager 2000 user.

L

line-of-business (LOB) application

An organization's primary business application. BizTalk Server 2002 supports numerous communication protocols that enable line-of-business applications to reliably send and receive information.

link

In Microsoft BizTalk Mapper, a simple value-copy (or name-copy) operation from a field in the source specification to a field in the destination specification, or to a functoid.

See also: functoid

long-running transaction

A collection of actions that send and receive messages over an indefinite period of time. Typically, long-running transactions contain several nested short-lived transactions.

See also: inner transaction, nested transaction, outer transaction, short-lived transaction, transaction

Loopback

A specific type of transport service that enables the return of current state data to the application from which the state data originated. Loopback uses the SubmitSync method call to restore the state data to the original application.

See also: transport services

looping record

A structure that can have more than one occurrence in instance documents. The structure can be an elemental record, consisting only of fields that hold content, or it can be a structure that has a nested hierarchical substructure.

M

manifest

A textual (typically XML) representation of a set of related configuration items, such as channel and port information, that are packaged together for use in deploying a single application or multiple applications from a test or staging environment to a production environment.

map

An XML file that defines the correspondence between the records and fields in one specification and the records and fields in another specification. A map contains an Extensible Stylesheet Language (XSL) style sheet that is used by BizTalk Server to perform the transformation described in the map. Maps are created in BizTalk Mapper.

See also: compile, data translation, Extensible Markup Language (XML)

mapping

The process of specifying the way in which data in one structure is transformed into another structure.

message

1. A packet of data that is sent or received by an XLANG schedule.

2. In BizTalk Orchestration Designer, a shape on the Data page that corresponds to the messages in an XLANG schedule. Message shapes are composed of uniquely named fields, each containing a single data item of a specified data type.

messaging port

A set of properties that directs how documents are enveloped, secured, and transported to a designated destination organization or application.

See also: distribution list

metadata

Data used to describe other data. For example, data type is a piece of metadata that further describes a property.

Microsoft Operations Manager (MOM)

An open, highly scalable, enterprise operations management and monitoring application in Microsoft Windows 2000 that enables centralized, dynamic monitoring and automated problem resolution of the events generated by users, application software, servers, and desktops.

MOM uses rules to monitor and generate a response to various events. This response can range from a user notification to an automated resolution of the problem.

mixed content

In XML, an element that contains both textual content and subelements. The element may or may not also carry attributes.

moniker

A name that represents an object and may include the complete path or address that identifies the location of the object.

See also: port

N

native

Any data that is not Extensible Markup Language (XML) data.

native instance

An instance of native data. For example, an EDI 850 (purchase order).

nested transaction

One or more transactions that are contained within the process flow of a larger transaction.

See also: inner transaction, long-running transaction, outer transaction, transaction

node path

An expression used to obtain XML element and attribute information, select data that matches specific criteria, and perform comparisons on the data retrieved. More formally known as XPath.

See also: XPath

non-self-routing document

A document that is missing one or more of the following pieces of routing information: source organization identifier, destination organization identifier, or document definition.

O

open channel

A channel that is explicitly declared as open to any source organization. The source data for an open channel is passed to BizTalk Messaging Services either within the document or in a parameter submitted with the document.

See also: channel, openness, source organization

open messaging port

A messaging port that is explicitly declared as open to any destination organization. The destination data for an open messaging port is passed to BizTalk Messaging Services either within the document or in a parameter submitted with the document.

See also: channel, openness, source organization

openness

A lack of explicit information about a source in a channel or destination in a messaging port. Channels contain information that identifies the source. Messaging ports contain information that identifies the destination. If a channel is designated as an open source, the source information is not explicitly declared in the channel and is provided by other means. Usually this information is contained in the instance of the document that is sent, or it is set as parameters in a Submit method call. Similarly, if a messaging port is designated as an open destination, the destination information is not explicitly declared in the messaging port and is instead provided in the document instance or in the parameters of a Submit method call.

See also: destination organization, open channel, open messaging port, source organization

organization

A trading partner or a business unit within a trading partner, or, in the case of the home organization, your own business.

See also: destination organization, organization identifier, trading partner, home organization, source organization

organization identifier

A set of properties that uniquely identifies an organization. An organization can have multiple organization identifiers. Organization identifiers consist of the following properties: a name, a qualifier, and a value.

See also: organization

outer transaction

A transaction that contains one or more transactions within its process flow.

See also: inner transaction, long-running transaction, nested transaction, transaction

output instance

A file resulting from the consumption of an input instance by the compiled style sheet.

See also: input instance

P

parser

A component of BizTalk Server that translates non-XML files (for example, X12, EDIFACT, and flat file) into XML files.

pass-through submission

A submission that bypasses the parsing, decoding, decryption, transformation, and signature verification stages of processing. The document instance is passed directly to the channel that is specified in the submission parameters. This type of submission can be used to transmit binary files without data corruption, or to use only the server transport and global tracking features.

See also: channel, document instance

per-instance queue

A queue that is created for use with each new instance of an XLANG schedule.

See also: static queue, dynamic queue

performance counters

Values that represent specific performance-related parameters for BizTalk Server 2002 and that are made available through the Microsoft Windows 2000 performance counter infrastructure. Performance counters are typically displayed using the Windows 2000 System Monitor standard utility, but might also be used by other applications, such as Microsoft Operations Manager (MOM).

persistence database

A database that is used to store the XLANG schedule state when an XLANG schedule is dehydrated. A default database called the Orchestration Persistence database is provided during installation when you install BizTalk Server 2002.

pipeline component

A component created to integrate applications with BizTalk Server 2002. Developers can use either the IPipelineComponent or the IPipelineComponentAdmin interface, or the lighter-weight IBTSAppIntegration interface, to develop these components.

pooling

Using COM+ object pools to limit the number of instances of a schedule or schedules that might be active and resident in memory at any one time.

port

A named location that uses a specific implementation. In BizTalk Orchestration Designer, a port is defined by the location to which messages are sent or from which messages are received, and the technology that is used to implement the communication action. The location is uniquely identified by the name of the port.

See also: binding, dynamic port, moniker, static port, port implementation, port location, port name, port reference

port group

A group of messaging ports that can be used to send the same document to several different trading partner organizations or applications. In BizTalk Messaging Manager, this is referred to as a distribution list.

port ID

A globally unique identifier (GUID) assigned by BizTalk Server 2002 to uniquely identify the port through which a document is processed.

port implementation

A specific technology used by a port to implement a communication action.

See also: port, port location, port name, port reference

port location

The location associated with a specific port. The location is also dependent on the port implementation that is used. Each implementation provides a different type of location for the port.

See also: port, port implementation, port name, port reference

port name

A unique identification for a port. This identification is used to correlate the port location with a specific port.

See also: port, port implementation, port location, port reference

port reference

A unique message that contains the port location for every port in an XLANG schedule. The Port References shape is located on the Data page. Any data flow into or out of this message contains the port location for a port.

See also: port, port implementation, port location, port name

positional flat file

A file that contains fields that are the same fixed length, and contains records that have a common end-of-record terminator.

provider

The source of information collected by Microsoft Operations Manager (MOM). Providers include system event logs and performance counters, among others.

See also: event consumer

Q

query

An expression used to locate information. In BizTalk Document Tracking, a query is an SQL statement that you use to extract tracking data from the Tracking database, using standard search criteria, such as source organization.

See also: advanced query

quiescent state

A state that represents processing activity that is inactive or at rest, or when a process is in standby mode.

R

receipt channel

A channel that contains the information necessary to process a receipt that can be returned to the sender of a document.

See also: channel

receive functions

Functionality that enables any BizTalk server(s) to monitor directories and submit documents to BizTalk Server for processing. BizTalk Server 2002 supports File, HTTP, and Message Queuing receive functions.

recipient

A trading partner that receives a SEED package from an initiating company (initiator) so that they can exchange business documents. A common scenario consists of a single company interacting with several trading partners of the same kind; the central company is called the initiator and the trading partners are called recipients.

See also: initiator, SEED package

rehydrate

To retrieve all state information for an XLANG schedule instance from a SQL Server database after a message is received by the XLANG Scheduler Engine.

See also: XLANG Scheduler Engine

reliable messaging

A feature of BizTalk Framework 2.0 protocol that supports guaranteed, once-only delivery of documents in heterogeneous environments across the Internet.

replication

The underlying process of copying data within a server. When a server has completed the replication process, it synchronizes the data to other servers.

resubmit

A procedure that submits interchanges or documents to BizTalk Server from the Suspended queue. The document is processed from the point of failure.

Retry queue

A table within the Shared Queue database in Microsoft SQL Server. The Retry queue is associated with a server group that contains items of work scheduled for transmission after an initial transmission has been attempted.

See also: Suspended queue, Work queue, Scheduled queue, Shared Queue database, transport services

routing logic

The set of rules that determines the sequence of execution within an XLANG schedule. Routing logic is implemented by the Decision shape in BizTalk Orchestration Designer.

S

Scheduled queue

A table within the Shared Queue database in Microsoft SQL Server. The Scheduled queue is associated with a server group that contains interchanges that have been received but not yet processed by BizTalk Server.

See also: Retry queue, Suspended queue, Work queue, Shared Queue database

schema

The definition of the structure of an XML file. A schema contains property information as it pertains to the records and fields within the structure.

SEED package

An XML package containing a company's business document configuration, which is created using BizTalk SEED Wizard. After a package is created, trading partners can use BizTalk SEED Wizard to install the configuration within their organizations in order to conduct business with the initiating company on the Web.

See also: initiator, recipient

selection criteria

A name-value pair designated in a document definition. The name-value pairs are used to uniquely identify a document definition for inbound EDI interchanges, based on values found in the functional group header, and to insert values in the functional group header for outbound EDI interchanges.

See also: document definition, electronic data interchange (EDI)

self-routing document

A document that contains all the necessary routing information, such as source and destination organization identifiers and a document definition, in the routing tags or within the document.

serializer

A component of BizTalk Server that translates XML files into non-XML files (for example, X12, EDIFACT, and flat files).

server group

A collection of individual servers that is centrally managed, configured, and monitored.

Shared Queue database

A Microsoft SQL Server database that is shared by all servers within a server group. The Shared Queue database stores all checkpoint information related to documents processed by BizTalk Server. If a server fails, other computers that use the same Shared Queue database can continue to retrieve messages from and post messages to the Work queue. This provides redundancy and process load balancing. The Shared Queue database is graphically presented in BizTalk Server Administration as a series of distinct queues.

See also: Retry queue, Scheduled queue, Suspended queue, Work queue

short-lived transaction

A collection of grouped actions that are performed as a single logical unit of work.

See also: long-running transaction, transaction

source

The name of the organization designated as the source for the channel through which a document is processed. Source is defined in BizTalk Messaging Services.

source application

A home-organization application that has been designated in a channel as the source of documents.

See also: channel, home organization

source organization

A trading partner organization that has been designated in a channel as the source of documents.

See also: channel, destination organization, open channel, open messaging port, openness, organization, trading partner

source specification

The specification in a map that represents the incoming document. BizTalk Mapper maps from a source specification to a destination specification.

See also: destination specification

specification

A BizTalk Server-specific XML schema. Specifications are created in BizTalk Editor and can be based on industry standards (such as EDIFACT, X12, and XML) or on flat files (delimited, positional, or delimited and positional). BizTalk Mapper uses specifications, opened as source specifications and destination specifications, to create maps.

state

The condition at a particular time of any of numerous elements of computing.

See also: XLANG schedule state

static port

A port that requires that all necessary information be provided for an XLANG schedule at design time. The designer who creates the XLANG schedule must know the location to which messages are sent or from which messages are received, as well as the technology chosen to implement the communication action.

See also: dynamic port, port

static queue

A queue that has a well-known address. Ports that use a Message Queuing implementation can use a static queue when the location of the queue is known and does not change.

See also: dynamic queue, per-instance queue

Suspended queue

A table within the Shared Queue database in Microsoft SQL Server. The Suspended queue is associated with a server group. The queue contains work items for which any error or failure was encountered during processing. The queue stores the documents until they can be corrected and reprocessed, or simply deleted.

See also: Retry queue, Scheduled queue, Shared Queue database, Work queue

synchronous communication

An interaction between two or more processes in which one process communicates with another, but cannot continue processing until it receives a specific response from the other process.

See also: asynchronous communication

T

topology

The organizational relationships between computers in a configuration. For example, one common topology in BizTalk Server is to have multiple processing servers sharing a single BizTalk Messaging Management database.

Tracking database

A Microsoft SQL Server database associated with a server group that enables the tracking of documents that are processed by the server either individually or in batches. You can also track XLANG schedule status.

trading partner

An external organization with which your home organization exchanges electronic data. The messaging ports, distribution lists, channels, and XLANG schedules that you create govern the exchange of documents among trading partners.

See also: channel, distribution list, home organization, organization, source organization

transaction

A discrete activity within a computer system, such as an entry of a customer order or an update of an inventory item, that consists of a group of operations that succeed or fail collectively. That is, if one operation fails, the entire transaction is rolled back, and the effects of any operations that took place before the failure are undone. Transactions are usually associated with database management, order-entry, and other online systems. In BizTalk Orchestration Designer, transactions are represented as a collection of actions that are grouped within a Transaction shape.

See also: abort, inner transaction, long-running transaction, nested transaction, outer transaction, short-lived transaction, commit

transaction set

A collection of segments in an EDI schema that has a specific order and a particular meaning for a particular business transaction.

transport services

A set of services that includes network protocols and application integration components (AICs). BizTalk Server 2002 supports a core set of transport services. This enables the server to send documents to organizations or applications whether or not the applications are capable of communicating directly with the server by using a COM interface. BizTalk Server 2002 supports the File, HTTP, HTTPS, and SMTP network protocols and Message Queuing. Transport services are also referred to as transport components.

See also: Loopback, Retry queue

U

user-defined rules

Microsoft Operations Manager (MOM) rules that are completely designed, created, and configured by a user.

See also: fully configured rules

V

version

In BizTalk Server 2002, either a specific release number for a specification or the industry-standard version number from which a specification is created.

W

Web Distributed Authoring and Versioning (WebDAV)

An extension to the HTTP 1.1 standard that exposes a hierarchical file storage media, such as a file system, over an HTTP connection. WebDAV locks documents to prevent users from accidentally overwriting each other's changes. It also enables users to share and work with server-based documents, regardless of their authoring tools, platforms, or the type of Web servers on which the files are stored.

well-formed XML

A standard that dictates that an XML document that has a single root and elements must nest completely or not at all.

Windows Management Instrumentation (WMI)

A management infrastructure in Microsoft Windows 2000 that supports monitoring and controlling system resources through a common set of interfaces and provides a logically organized, consistent model of Windows operation, configuration, and status. BizTalk Server 2002 uses the WMI layer to encapsulate administrative functions.

Work queue

A table within the Shared Queue database in Microsoft SQL Server. The Work queue is associated with a server group. It contains interchanges that are currently being processed by BizTalk Server 2002.

See also: Retry queue, Scheduled queue, Shared Queue database, Suspended queue

X

XLANG identity

A globally unique ID that is used to distinguish version instances of an XLANG schedule drawing. This property is read-only and cannot be changed. Every time an XLANG schedule drawing is updated, this identity is also updated. The XLANG identity can be used to correlate an XLANG schedule with the specific version of an XLANG schedule drawing from which the schedule was compiled.

XLANG language

A language that describes the logical sequencing of business processes, as well as the implementation of the business process by using various implementation technologies. The XLANG language is expressed in XML.

XLANG schedule

Specific business processes expressed in the XLANG language. An XLANG schedule is saved with the file extension .skx.

See also: XLANG Scheduler Engine, XLANG schedule drawing, XLANG schedule instance

XLANG schedule drawing

A drawing that represents a business process. In BizTalk Orchestration Designer, once a drawing is complete, it can be compiled and run as an XLANG schedule. An XLANG schedule drawing is saved with the file extension .skv.

See also: XLANG schedule, XLANG Scheduler Engine, Communication shapes, Flowchart shapes

XLANG schedule instance

An evocation of a schedule. An XLANG schedule represents only the business process and implementation services. A single instance, or multiple instances, of an XLANG schedule can be run by the XLANG Scheduler Engine. Different instances of the same XLANG schedule contain different messages, but all instances follow the same business-process rules.

See also: XLANG schedule, XLANG Scheduler Engine

XLANG schedule state

The information contained in an XLANG schedule instance. This information includes messages that have been sent or received by that instance, any COM objects used by that instance, and the progress of that instance toward the completion of the business process.

See also: state

XLANG Scheduler

The default COM+ application that is installed when you install BizTalk Server 2002. This application is used to host running instances of XLANG schedules.

XLANG Scheduler Engine

A service that runs XLANG schedule instances and controls the activation, execution, dehydration, and rehydration of an XLANG schedule.

See also: dehydrate, rehydrate, XLANG schedule, XLANG schedule drawing, XLANG schedule instance

XML-Data Reduced (XDR)

An XML Schema dialect proposed by Microsoft and submitted to the World Wide Web Consortium (W3C) in 1998. Like XML-Data, XDR is a syntax for Extensible Markup Language (XML) schemas that define the characteristics of an XML document. XDR is a subset of XML-Data.

See also: Extensible Markup Language (XML)

XPath

A comprehensive language used for navigating through the hierarchy of an XML document. XPath expressions can obtain XML element and attribute information, select data that matches specific criteria, and perform comparisons on the data retrieved. Also called a node path.

See also: Extensible Markup Language (XML), node path


.topic 5
Select this check box to enable the COM+ application to run XLANG schedule instances.

.topic 8
Select this check box to use a file DSN to reference the persistence database for this COM+ application. If this check box is not selected, a system or user DSN is used. A file data source name (DSN) stores information about a database connection in a file. The file has the extension .dsn and by default is stored in the $\Program Files\Common Files\ODBC\Data Sources directory.

.topic 3
This field contains the name of the DSN used to communicate with the persistence database for this COM+ application. The DSN name must always be the same as the name of the COM+ application.

.topic 2
Click this button to create the ODBC data source name (DSN) for the COM+ application that hosts the XLANG Scheduler Engine. Important: The name of the Data Source Name configured in the XLANG Scheduler Properties dialog box must be the same as the name of the COM+ application.

.topic 1
Click this button to open the ODBC Data Source Administrator to manage any data sources you have defined on this computer.

.topic 4
Click this button to create the tables required to support persistence for XLANG schedule instances in a SQL Server database.

.topic 7
Click this button to gracefully shut down all running XLANG schedule instances. The schedule state for any running schedules is stored in the persistence database.

.topic 6
Click this button for all running COM+ applications that host XLANG schedule instances to initiate the rehydration of the schedule instances, and if possible, continue running them.


Support Online

Online Support
and Information

* | Microsoft BizTalk Server Web site
* | Microsoft Product Support Services Web site
* | Microsoft COM Web site
* | Microsoft Message Queuing Web site
* | Microsoft SQL Server Web site
* | Microsoft Windows Script Technologies Web site
* | Microsoft XML on MSDN Online
* | MSDN Online
* | MSDN Library
* | Microsoft Accessibility Web site


Legal Information Microsoft BizTalk Server 2002

BizTalk Server 2002 ~ Copyright

Legal Information
Microsoft BizTalk Server 2002

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1999-2001 Microsoft Corporation. All rights reserved.

Microsoft, Active Directory, ActiveX, BizTalk, FrontPage, JScript, MSDN, MS-DOS, Visio, Visual Basic, Visual C++, Visual C#, Visual InterDev, Visual Studio, Win32, Windows, and Windows NT, are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Intel is a registered trademark of Intel Corporation.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.