Spread for Biztalk Developer's Guide

Developer’s Guide

Spread™ for Microsoft® BizTalk® Server

Legal Notices

Information in the documentation is subject to change without notice and does not represent a commitment on the part of GrapeCity, Inc. The software described in this document is furnished under a license or non-disclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy this software on any medium except as is specifically allowed in the license or non-disclosure agreement. No part of the documentation may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose without the express written permission of GrapeCity, Inc.

Unless otherwise noted, all names of companies, products, street addresses, and persons contained herein are part of a completely fictitious scenario or scenarios and are designed solely to document the use of a GrapeCity, Inc., product.

FarPoint Spread is a trademark of GrapeCity, Inc.

Microsoft, BizTalk, Excel, Visual Basic, Visual C#, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States or other countries. Other brand and product names are trademarks or registered trademarks of their respective holders.

Distribution Restrictions If you are using the trial or evaluation version of this product, then you may not distribute any of the files provided with the trial or evaluation version. The component assemblies (DLLs) may be deployed on your development machines, test servers and on your production server. Distribution by the user of any designers or design-time assistants (EXEs or DLLs), executables, or source code distributed by GrapeCity as part of this product is prohibited. You shall not develop applications that provide an application programmable interface to the Software or the Software as modified nor may you create Web Services with the Software without the appropriate license from GrapeCity. Redistribution by your users of GrapeCity' assemblies (DLLs) or your modified or wrapped version of our assemblies without the appropriate redistribution license from GrapeCity is prohibited.

ii Spread for BizTalk Developer’s Guide

Dedication

This documentation was written as a collaborative effort by employees. Developers, technical support personnel, testers, and technical writers all added their knowledge of how the product works and can best be applied. This documentation is a diverse collection that follows a tradition of extensive examples and code snippets to clarify the use and flexibility of our product. Because the world of software development and the computer-based economy are changing so rapidly, developers like you need a tool that is flexible and extendable, and you do not have a lot of time to learn how best to apply it. A well-supported and well-documented product is necessary for success.

Recognizing that there are various levels of readers, from beginners with pipeline components, to experienced BizTalk consultants, we have tried our best to provide essential procedural documentation to help you get started as well as detailed reference documentation to let you customize the use of the product to the fullest extent.

We dedicate this documentation to the developers who can think beyond the traditional boundaries of spreadsheets and use this product to extend their creative and innovative ideas.

Spread for BizTalk Developer’s Guide iii

Table of Contents

Dedication ...... iii

Overview ...... 1

Disassembling Spreadsheet Input ...... 4

Working with Originating Spreadsheet Files ...... 5

Adding a Spreadsheet Disassembler to a Receive Pipeline ...... 6

Selecting the Input XML Document Schema for the Disassembler ..... 10

Testing the Pipeline with the Spreadsheet Disassembler ...... 12

Mapping Inputs and Outputs ...... 17

Pipeline Property Assignment ...... 18

Assembling Document Output ...... 19

Adding a Document Assembler to a Send Pipeline ...... 19

Selecting the Output XML Document Schema for the Assembler ...... 22

Designing the Format for the Document Assembler ...... 25

Viewing (and Reviewing) the Output Documents ...... 25

Using the Spreadsheet Schema Wizard ...... 26

Select the Spreadsheet File for Schema Information (Wizard Screen)27

Select Additional Schema Settings (Wizard Screen) ...... 28

Select the Data Range (Wizard Screen) ...... 29

Select the Entity Mapping (Wizard Screen) ...... 30

Seeing the Resultant Spreadsheet Schema ...... 34

Using the Spreadsheet Format Designer ...... 35

Adjust Sizes ...... 36

Add Images ...... 36

Format Rows ...... 36

Format Columns ...... 37

(continued) iv Spread for BizTalk Developer’s Guide

Format a Sheet ...... 39

Reset the Design ...... 40

Glossary ...... 43

CLS Compliance Notes ...... 47

Getting Technical Support ...... 48

Contacting Us ...... 49

Spread for BizTalk Developer’s Guide v

vi Spread for BizTalk Developer’s Guide

Spread for Microsoft BizTalk Server

Overview

The Spread for Microsoft® BizTalk® Server (which we simply call "Spread") offers a way to handle Excel spreadsheet data as input and provide documents as outputs allowing you to create a completely automated handling of spreadsheet data in your BizTalk process. Spread integrates with Microsoft BizTalk Server 2006 and is compatible with R2.

Generally, there are two tasks that Spread can automate in your BizTalk process - disassembling spreadsheet input (typically parsing Excel data) and assembling document output (typically creating Excel or PDF documents). These tasks of handling spreadsheet data can be done independently or in concert in a BizTalk process; you may only be interested in automating one of these tasks or you may do both. For more information see the SpreadOverview. The Disassembler automates the parsing of Excel message streams to XML message streams for Excel integration with Microsoft BizTalk Server 2006. It provides you a codeless solution to parse Excel spreadsheet into XML. At the design time, the Spreadsheet Wizard helps you develop a custom schema based on the Excel sheet and at the runtime, the Excel is parsed and disassembled into XML. With a Format Designer you can customize the appearance of output documents, which can be either Excel or PDF documents.

This documentation assumes you have some familiarity with developing projects in Microsoft Visual Studio and with handling components with Microsoft BizTalk Server 2006. For more information on those topics refer to Microsoft documentation. You should have already installed Spread following the instructions in the Read Me file.

Spread is not CLS-compliant because the Microsoft .NET interfaces required to communicate with Microsoft BizTalk Server 2006 at runtime and with Microsoft Visual Studio at design time are not CLS-compliant. For more details, see CLS compliance note.

Spread for BizTalk Developer’s Guide 1

2 Spread for BizTalk Developer’s Guide

Using Spread for BizTalk involves the following tasks:

Disassembling Spreadsheet Input

* Working with Originating Spreadsheet Files

* Adding a Spreadsheet Disassembler to a Receive Pipeline

* Selecting the Input XML Document Schema for the Disassembler

* Creating the Input Spreadsheet Schema with the Wizard

* Testing the Pipeline with the Spreadsheet Disassembler

Mapping Inputs and Outputs

Assembling Document Output

* Adding a Document Assembler to a Send Pipeline

* Selecting the Output XML Document Schema for the Assembler

* Designing the Format for the Document Assembler

* Viewing (and Reviewing) the Output Documents

Spread for BizTalk Developer’s Guide 3

Disassembling Spreadsheet Input

Spread integrates spreadsheet files as inputs for a completely automated handling of spreadsheet data in your BizTalk process.

Before you set up Spread, be sure to take a look at the spreadsheet files that are regularly received into your BizTalk process. Look over the files to see the parts of the data you are extracting into XML streams that are used elsewhere in your business process.

Here are the steps to using Spread to automate the disassembling of spreadsheet input.

. Working with Originating Spreadsheet Files . Adding a Spreadsheet Disassembler to a Receive Pipeline . Selecting the Input XML Document Schema for the Disassembler . Creating the Input Spreadsheet Schema with the Wizard . Testing the Pipeline with the Spreadsheet Disassembler

4 Spread for BizTalk Developer’s Guide

Working with Originating Spreadsheet Files

Valid file types that serve as input into the Spread disassembler are.

. Excel 97-2003 Workbook (XLS) Files . Excel Workbook (XLSX) – Office Open XML (OOXML) – Files . Comma-Separated (CSV) Files . Text (tab-delimited) (TXT) Files

After to look over the file or files, you are ready to open a BizTalk project in Visual Studio and add the Spreadsheet disassembler component (to the receive pipeline) that will parse the Excel (XLS) file.

Excel 97-2003 Workbook (XLS) Files

Microsoft® Excel® (or Excel-formatted) XLS files are the most common inputs into Spread. These may have multiple sheets and each sheet can be handled by Spread.

Make sure that you have closed the Excel files before working with Spread. (Microsoft Excel locks an open file so that it can not be used by other applications.)

The information about Excel and Excel files in this documentation is based on BIFF8 (Binary Interchange File Format, version 8 from Microsoft) which is the file format for several versions of Microsoft Excel (Excel 97, Excel 2000, and Excel XP). If you are working with custom-created XLS files (not necessarily created in Microsoft Excel), you may want to first check with FarPoint to ensure compatibility with Spread.

The figure below briefly summarizes some aspects of an example Excel file.

Spread for BizTalk Developer’s Guide 5

Excel Workbook (XLSX) – Office Open XML (OOXML) – Files

Spread supports Microsoft Office Open XML (OOXML) file format for newer Excel files. This is also referred to as Office 2007 (or Excel 2007).

Comma-Separated (CSV) Files

Spread also accepts tabular data stored as comma-separated values (or CSV) files. CSV is one type of delimited text file, which uses a comma to separate (delimit) values and uses a " (double-quote) character around fields that contain reserved characters (such as commas or forced lines).

Text (tab-delimited) (TXT) Files

Spread also accepts tabular data stored as tab-delimited text files. TXT is one type of delimited text file, which uses a tab to separate (delimit) values.

Adding a Spreadsheet Disassembler to a Receive Pipeline

This topic provides an overview of how to add the Spread spreadsheet disassembler component to a receive pipeline in a BizTalk Server project in Visual Studio.

In Visual Studio, open the BizTalk Server project and add a Receive Pipeline to the BizTalk Server project. The figure below shows a screen shot of an example BizTalk Server project and you can see the receive pipeline is listed in the Solution Explorer

6 Spread for BizTalk Developer’s Guide

window of Visual Studio. The process diagram on the right shows the components for that pipeline.

From the Toolbox, under BizTalk Pipeline Components, select the Spreadsheet Disassembler (which is available when you install Spread). Add the Spreadsheet Disassembler component by dragging that component to the receive pipeline and dropping it on the Disassemble stage of the Receive Pipeline as shown in this figure.

Spread for BizTalk Developer’s Guide 7

Besides dropping it on the Disassemble stage, you could also drop the Spreadsheet Disassembler component on either the Decode or Validate stage, if you wish. Any of these three stages are allowed.

Now you are ready to set the properties of the Spreadsheet Disassembler and select the XML Document Schema for that disassembler component of the pipeline.

The Spreadsheet Disassembler component of Spread for BizTalk includes the Password property. A password can be entered at design time in Visual Studio and that password will be used to open all documents that pass through this component. The password is displayed in the property grid as a string of dots.

8 Spread for BizTalk Developer’s Guide

Spread for BizTalk Developer’s Guide 9

Selecting the Input XML Document Schema for the Disassembler

This topic provides an overview of how to add a Document Schema (or Schemas) for the Spreadsheet disassembler of the receive pipeline component of the BizTalk Server project. This assumes that you have previously added the Spreadsheet Disassembler to the receive pipeline.

Spread supports multiple schemas. Multiple schemas can be set to allow Spread to parse various types of Excel formats or various Excel templates. This allows you to handle different formats of incoming files automatically. The Document Schema property is SchemaList. At design time (in Visual Studio) the property brings up the Visual Studio schema collection editor. At runtime the schemas are applied against the incoming message stream until a schema (beginning with the first in the list) succeeds or they all fail and an error event is logged with BizTalk.

In Visual Studio, in the BizTalk Server project, open the Properties window of the Spreadsheet Disassembler. In the category of Pipeline Component Properties, select the DocumentSchema property. Since this is a collection, clicking on the Collection button brings up the Schema Collection Property Editor. In this editor, you can select any of several default document schemas that come with the BizTalk Server or a document schema that you have created. Select from the available schemas and add them as needed. Click OK when done. An example of the collection editor is shown in this figure.

To create a Document Schema that will parse the Excel data into your XML stream, add a new Schema File to the BizTalk project. Right-click on the BizTalk Server Project in the

10 Spread for BizTalk Developer’s Guide

Solution Explorer and select Add New Item. In the Add New Item dialog, select Schema File, as shown in this figure.

In the Categories area, under BizTalk Project, select Schema.

In the Templates area, under Visual Studio installed templates, select Spreadsheet Schema Wizard. The Spreadsheet Schema Wizard is also part of Spread.

In the Name field, you can either accept the default name that is generated or type in a name for the spreadsheet schema.

When you are done, click Add, and this launches the Spreadsheet Schema Wizard.

Now you are ready to see how to use the Spreadsheet Schema Wizard. Refer to Using the Spreadsheet Schema Wizard section.

Spread for BizTalk Developer’s Guide 11

Testing the Pipeline with the Spreadsheet Disassembler

This topic provides an overview of how to test the Spreadassuming you have previously completed these tasks:

. created the Spreadsheet Schema with the wizard . selected and added that Spreadsheet Schema to the Disassembler as its XML Document Schema

When successful, the schema is created and added to the solution. Now you can look at the schema and see the parts that are relevant to converting your data. The hard part is done. The final steps include:

. Validate the XML instance . Add the schema to the spreadsheet disassembler . Build (or Re-build) the solution . Deploy the solution on the BizTalk Server

Validate the XML Instance

In VisualStudio, look at the properties of the spreadsheet schema that is added to the project.

12 Spread for BizTalk Developer’s Guide

Select the schema item and right-click. Select Properties. The Property Pages window opens. Under the General category, the Input Instance Filename has the name of the Excel file that was used to create the schema. That is used to validate the instance:

Spread for BizTalk Developer’s Guide 13

Again with the schema item selected, right-click, and select Validate Instance. The Excel data is parsed and the XML is generated. That XML is validated against the schema to verify that the XML is valid.

Add the Schema to the Spreadsheet Disassembler

For information about adding the schema to the spreadsheet disassembler component of the receive pipeline, refer to Adding a Spreadsheet Disassembler to a Receive Pipeline. Make sure the DocumentSchema property is set to the Spreadsheet schema previously created and validated.

Build (or Re-build) the Solution

With the DocumentSchema property set to the Spreadsheet schema previously created and validated, rebuild the solution (as shown in this figure).

14 Spread for BizTalk Developer’s Guide

Deploy the Solution on the BizTalk Server

When the solution is built, you can deploy the solution on your BizTalk Server.

BizTalk RunTime and Password Protected Files

Spread for BizTalk Developer’s Guide 15

If the password is correct, then the password protected document will process correctly. If there are documents that fail to open due to invalid passwords, the error will be reported and contained in the Event Viewer.

16 Spread for BizTalk Developer’s Guide

Mapping Inputs and Outputs

Between Assembling and Disassembling, you can do mapping to transform XML inputs to XML outputs in your business process in Microsoft BizTalk.

In Visual Studio, in the project, add a Map. The screen shot above shows a map that is added to the Order Invoice example that provides mapping of the Excel input to an order invoice output.

Spread for BizTalk Developer’s Guide 17

Pipeline Property Assignment

Here are some notes about property assignment and reassignment.

Receive Pipeline FileName Property

If the Receive Location Transport Type in the recieve pipeline is POP3, the Disassembler reassigns the MIME.FileName property value to the FILE.ReceivedFileName so the attachment name can be accessed via the %SourceFileName% BizTalk Macro.

Send Pipeline FileName Properties

The Assembler assigns the DocumentName property value, with the appropriate file extension (.XLS, .XLSX, or .PDF), to the following BizTalk properties:

. MIME.FileName . FILE.ReceivedFileName . FTP.ReceivedFileName . WSS.FileName

If no DocumentName is specified, "docOut", with the appropriate file extension, is assigned to the BizTalk properties.

18 Spread for BizTalk Developer’s Guide

Assembling Document Output

Spread creates documents as outputs for a completely automated handling of spreadsheet data in your BizTalk process.

Before you set up Spread, be sure to think about the desired output files to produce, which can be Excel (XLS or XLSX) or PDF documents.

. Adding a Document Assembler to a Send Pipeline . Selecting the Output XML Document Schema for the Assembler . Designing the Format for the Document Assembler . Viewing (and Reviewing) the Output Documents

Adding a Document Assembler to a Send Pipeline

This topic provides an overview of how to add the Spread document assembler component to a send pipeline in a BizTalk Server project in Visual Studio.

In Visual Studio, open the BizTalk Server project and add a Send Pipeline to the BizTalk Server project. The figure below shows a screen shot of an example BizTalk Server project. The send pipeline is listed in the Solution Explorer window of Visual Studio. The process diagram on the right shows the components for that pipeline.

Spread for BizTalk Developer’s Guide 19

From the Toolbox, under BizTalk Pipeline Components, select the Document Assembler (which is available when you install Spread). Add the Document Assembler component by dragging that component to the send pipeline and dropping it on the Assemble stage of the Send Pipeline as shown in this figure.

20 Spread for BizTalk Developer’s Guide

Besides dropping it on the Assemble stage, you could also drop the Document Assembler component on either the Decode or Validate stage, if you wish. Any of these three stages are allowed.

Now you are ready to set the properties of the Document Assembler and select the XML Document Schema for that assembler component of the pipeline.

The Spreadsheet Assembler component of Spread for BizTalk includes the Password property. A password can be entered at design time in Visual Studio and that password will be used when creating all documents that pass through the component. The password is displayed in the property grid as a string of dots.

Spread for BizTalk Developer’s Guide 21

Selecting the Output XML Document Schema for the Assembler

This topic provides an overview of how to add a Document Schema (or Schemas) for the document assembler of the send pipeline component of the BizTalk Server project. This assumes that you have previously added the document assembler to the receive pipeline.

In Visual Studio, in the BizTalk Server project, open the Properties window of the Document Assembler. In the category of Pipeline Component Properties, select the DocumentSchema property. Since this is a collection, clicking on the Collection button brings up the Schema Collection Property Editor. In this editor, you can select any of several default document schemas that come with the BizTalk Server or a document

22 Spread for BizTalk Developer’s Guide

schema that you have created. Select from the available schemas and add them as needed. Click OK when done. An example of the collection editor is shown in this figure.

To create a Document Schema that will parse the Excel data into your XML stream, add a new Schema File to the BizTalk project. Right-click on the BizTalk Server Project in the Solution Explorer and select Add New Item. In the Add New Item dialog, select Schema File, as shown in this figure.

Spread for BizTalk Developer’s Guide 23

In the Categories area, under BizTalk Project, select Schema.

In the Templates area, under Visual Studio installed templates, select Spreadsheet Schema Wizard. The Spreadsheet Schema Wizard is also part of Spread.

In the Name field, you can either accept the default name that is generated or type in a name for the spreadsheet schema.

When you are done, click Add, and this launches the Spreadsheet Schema Wizard.

Now you are ready to see how to use the Spreadsheet Schema Wizard. Refer to Using the Spreadsheet Schema Wizard section.

To speed the process, you may want to create a spreadsheet template in Microsoft Excel or in FarPoint Spread for Windows Forms and save the file as an XLS or XLSX file. Typically, the spreadsheet would have at least one row of data with the columns that you would want in your output, it would have a header row with the column names, and it may have a trailer row with summary information such as totals.

24 Spread for BizTalk Developer’s Guide

Designing the Format for the Document Assembler

This topic provides an overview of how to design the format of the output document, for the output assembler of the send pipeline component of the BizTalk Server project. This assumes that you have previously added the document assembler to the send pipeline.

In Visual Studio, in the BizTalk project, with the send pipeline selected, select the Format template property and click on the button in that property. This launches the Format Designer.

Now you are ready to see how to use the Spreadsheet Format Designer. Refer to the Using the Spreadsheet Format Designer section.

When you are done with the Format Designer, you can select that template in the Format template property.

In the Spreadsheet format property, select the output file type (XLS, XLSX, or PDF).

Now you are finished selecting the template and specifying the output document format.

Viewing (and Reviewing) the Output Documents

This topic provides an overview of how to test the Spreadassuming you have previously completed these tasks:

. created the Spreadsheet Schema with the wizard . selected and added that Spreadsheet Schema to the Disassembler as its XML Document Schema . formatted the output using the Format Designer

. Validate the XML instance . Add the schema to the spreadsheet disassembler . Build (or Re-build) the solution . Deploy the solution on the BizTalk Server

Spread for BizTalk Developer’s Guide 25

Using the Spreadsheet Schema Wizard

When you are working in a BizTalk project and you need to add a Spreadsheet Schema to the Spreadsheet Disassembler, you launch the Spreadsheet Schema Wizard.

The wizard opens with the Welcome screen:

To make use of the wizard, click Next to continue.

The subsequent screens in the Schema Wizard are:

. Select the Spreadsheet File for Schema Information . Select Additional Schema Settings . Select the Spreadsheet Data . Select the Entity Mapping . (and you can see the resultant Spreadsheet Schema)

26 Spread for BizTalk Developer’s Guide

Select the Spreadsheet File for Schema Information (Wizard Screen)

After the Welcome screen, the next screen in the wizard is the "Select the Spreadsheet File for Schema Information" screen:

Specify the spreadsheet file that you want to use for schema information. You can either type the complete path and file name in the text box or click Browse and browse to the file in the File window.

A default target namespace is given, and you may edit the target namespace as needed. This will be the namespace for the XML schema that is generated by this wizard that will then be used in the Spreadsheet Disassembler.

Select the code page; the code page specifies the character set that will be used with the XML schema for encoding the XML. The drop-down list contains the code pages available as shown in this figure.

Spread for BizTalk Developer’s Guide 27

When you are done selecting the spreadsheet file, click Next to continue. This displays the Select Additional Schema Settings (Wizard screen).

Select Additional Schema Settings (Wizard Screen)

After the Select the Spreadsheet File for Schema Information screen, the next screen in the wizard is the "Select Additional Schema Settings" screen:

Here you select any or all of the additional settings listed in a check box fashion.

When you are done selecting settings, click Next to continue. This displays the Select the Data Range (Wizard screen).

The wizard user is prompted to enter a password when using a password protected Excel document as a template for creating a schema. If a valid password is entered, the wizard will continue; otherwise, the wizard displays an error and allows the user another opportunity to enter a valid password for the document.

Here is more information on each of the settings.

Removing Hidden Columns in Data

If you have hidden columns in your incoming spreadsheet data and you do not want to have these columns in the the resulting XML, check the box for handing hidden columns. By default the box is unchecked, and hidden columns are included like any other column.

Filling Cell Spans in Data

If you have any spans in your incoming spreadsheet data and you want to fill all the cells in that span with the value in that span, check the box for handling cell spans. By default

28 Spread for BizTalk Developer’s Guide

the box is unchecked, so spans are not handled. With the box checked, FarPoint Spread for BizTalk copies the visible data in a span to every cell within that span.

Parsing Multiple Sheets

For those Excel workbooks with multiple sheets that use the same schema for multiple sheets in that workbook, here is an option to simplify the parsing. With this option selected, the last sheet of selected data in the workbook is used as the basis for creating the schema for any number of sheets in the workbook. FarPoint Spread for BizTalk can handle Excel files with variable number of sheets. This saves having to generate a schema for each sheet, which is useful when there are many sheets in the workbook that could use the same schema and when the number of sheets can vary. By default, this option is not selected since most users have schemas for each sheet.

Using Sheet Names in Data

If you want to override the default sheet attribute in the schema generation, you can unselect this option (uncheck the box) for handling sheet names. By default, this option is selected, and the sheet names are used in the schema as record item parent node attributes.

For example, if you have a sheet name such as "AL" and you keep the default settings, after parsing, the resulting XML would be: ...

If you uncheck the, "Use the sheet names as record item parent note attributes" option, then the resulting XML would be: ...

Select the Data Range (Wizard Screen)

After the Select Additional Schema Settings screen, the next screen in the wizard is the "Select Spreadsheet Data" screen:

Spread for BizTalk Developer’s Guide 29

Here you click on the data in the window, which has loaded the data from your Excel file, with sheet name tabs at the bottom and header cells for each row and column, just as in Excel. As the wizard screen instructs, select all the data in the Excel file to define the records. Select the rows of data by dragging over the rows of interest.

For example, as shown in the figure above, select the rows in the data area and ignore the header and footer rows and spacer (empty) rows. (For a quick review, refer to the picture of an Excel file on page 3.)

If the spreadsheet file has several sheets, select the data rows for each sheet. You can move from one sheet to another by clicking on the sheet name tabs. In this example, the sheets are named "Sheet1", "Sheet2", and "Sheet3" which are by default. If your spreadsheet file had sheet names, they would import. You do not need to select data in every sheet if you only need data from some of the sheets.

When you are done selecting data rows, click Next to continue. This displays the Select the Entity Mapping (Wizard screen).

Select the Entity Mapping (Wizard Screen)

After the Select Spreadsheet Data screen, the next screen in the wizard is the "Select the Entity Mapping" screen:

30 Spread for BizTalk Developer’s Guide

The data you selected previously is displayed with some editable columns as explained below. Scroll bars and sheet name tabs are displayed to allow you to navigate to all the columns of data. With the data selected from the previous wizard screen, now you can set how each column of data is translated into XML schema entities. Each column is considered a field. In this screen, you can click on column header cells if you want to change either the field name or field type or data type for the data in that column. The schema mapping properties are:

. Field Name . Field Type . Data Type

Spread for BizTalk Developer’s Guide 31

Field Name

By default, the field names (for each column) would be Column0, Column1, Column2, etc. In the example shown here, the field names were imported from the spreadsheet file from the row above the data. This is done by Spread to help you save time. If you want to change the names, you can simply click in the cell for that field name and type in a new name or change what is there.

Field Type

The field type can be either Element or Attribute, meaning either the data is an XML element or simply an XML attribute in the resultant schema. In the example shown here, the first column "Part Number" is selected and its field type can be changed to Attribute.

Data Type

The data type is determined initially by Spread when the spreadsheet file is loaded. Spread looks at each data item in the column and determines the best data types for those items; it creates a list of the most general data types that all the items in that column could be coerced to. A drop-down list is available for the data types. In the

32 Spread for BizTalk Developer’s Guide

example shown here, the Part Number could be coerced to fit a double-precision floating point number (Double), or a single-precision floating point number (Float) or a Date- Time or a string. In this example, Double is selected.

Be sure to set the entity mapping for all sheets of interest. If you did not select any data in the previous screen of the wizard (Select the Spreadsheet Data), then it does not appear in this screen of the wizard. FarPoint Spread for BizTalk is intelligent enough to know that you are not interested in that sheet.

When you are done setting all the entity mappings for all the data, click Finish to continue. This will complete the wizard and FarPoint Spread for BizTalk will generate the Spreadsheet Schema based on the information you have provided. Next, you can see the resultant Spreadsheet Schema.

Spread for BizTalk Developer’s Guide 33

Seeing the Resultant Spreadsheet Schema

After the Select Entity Mapping screen, Spread generates a Spreadsheet Schema based on the information provided in the wizard. The result is added to the BizTalk Server project and is shown in Visual Studio. The figure below shows the example from these steps.

The resultant schema includes many aspects of the original data, even those aspects which you did not select explicitly in the schema wizard. For example, Spread allows the unselected data to persist as "unmapped" data, since at some future time, that data may be used in the parsing process. Headers and trailers are preserved as elements in the schema. Spacer rows within the data are not persisted, but spacer rows prior to or following the data are persisted.

And that's about all there is to it! Once you have selected the Excel file, chosen the data, and specified the entity mapping, Spread does the rest.

34 Spread for BizTalk Developer’s Guide

Using the Spreadsheet Format Designer

You can create the output design using the Assembler Spreadsheet Format Designer.

With the Format Designer you can:

. Adjust Sizes . Add Images . Format Rows . Format Columns . Format a Sheet . Reset the Design

Each of these is discussed in turn below.

Spread for BizTalk Developer’s Guide 35

Adjust Sizes

You can adjust sizes of rows and columns in the output using the Format Designer.

You can adjust sizes by selecting the header resize bar between two columns or rows.

Add Images

You can add and remove images to the output using the Format Designer.

From the Images menu, select Add.

Browse to the file, which can be any of these graphic file types:

. BMP - bitmap file format . GIF - Graphics Interchange Format, an 8-bit-per-pixel bitmap image format . PNG - Portable Network Graphics image format

Once inserted, you can move and resize the graphic image.

Format Rows

You can format rows of data in the output using the Format Designer.

36 Spread for BizTalk Developer’s Guide

You can customize these aspects of row formatting:

. Color . Font . Insert . Height . Reset

With one or more rows selected, you can set the background color or text color (or both) for those rows. Select Color and, from the color picker that displays, select the color.

With one or more rows selected, you can set the font for those rows. Select Font and, from the font dialog that displays, select the font settings including the face, the color, and the size.

You can also insert a blank row, typically to allow adding an image above or below the data. Select Insert and then select where to insert that row.

With one or more rows selected, you can set the height of those rows. Select Height and, from the Row Height dialog that displays, enter the height in pixels. Another way to adjust the height of the row is to select the bar between two row headers and drag it to the desired height.

You can also reset individual row settings back to the default values by selecting the Reset choice. For example to return the row height to the default value, select Reset Height. To reset the entire spreadsheet to default values, use the Reset menu.

Set the formatting settings and click OK when done.

Format Columns

You can format columns of data in the output using the Format Designer.

Spread for BizTalk Developer’s Guide 37

You can customize these aspects of column formatting:

. Alignment . Color . Font . Data Format . Width . Reset

With one or more columns selected, you can set the alignment of text for those columns. Select Alignment and, from the drop-down menu that displays, select either Left, Center, or Right, for left-justified, center-justified, or right-justified text respectively.

With one or more columns selected, you can set the background color or text color (or both) for those columns. Select Color and, from the color picker that displays, select the color.

With one or more columns selected, you can set the font for those columns. Select Font and, from the font dialog that displays, select the font settings including the face, the color, and the size.

With one or more columns selected, you can set the format for the data in those columns. Select Data Format and follow the instructions given in the section below.

With one or more columns selected, you can set the width of those columns. Select Width and, from the Column Width dialog that displays, enter the width in pixels. Another way to adjust the width of the column is to select the bar between two column headers and drag it to the desired width.

You can also reset individual column settings back to the default values by selecting the Reset choice. For example to return the column width to the default value, select Reset Width. To reset the entire spreadsheet to default values, use the Reset menu.

Set the formatting settings and click OK when done

Data Format

From the Column menu, select Format.

38 Spread for BizTalk Developer’s Guide

The Column Data Format dialog is displayed as shown here.

Select whether the data is numerical, date-time, or text by selecting the appropriate tab.

For numerical data, you can format the data as numbers, percents, or currency values. Select from the choices available to customize the formatting of the data and click OK when done.

For date-time data, you can format the date and time using the formatting string (and using either short or long). Click OK when done.

For text, you can format the data as text and select whether to allow wrapping to multiple lines in a cell. Click OK when done.

Format a Sheet

You can format a sheet for the output using the Format Designer.

From the Sheet menu, select Settings.

Spread for BizTalk Developer’s Guide 39

In the Sheet settings dialog select or de-select the options that affect the sheet formatting.

Option Description Show horizontal When checked, the horizontal grid lines are displayed in the grid lines output spreadsheet (which they are by default) Show vertical grid When checked, the vertical grid lines are displayed in the output lines spreadsheet (which they are by default) When checked, the automatically numbered row headers are Show row headers displayed in the output spreadsheet (which they are by default) Show column When checked, the automatically lettered column headers are headers displayed in the output spreadsheet (which they are by default)

When done, select OK.

Reset the Design

You can reset the design back to the default spreadsheet design using the Format Designer. Select Reset from the menu. A confirmation dialog is displayed, as shown here.

Click Yes to reset the entire spreadsheet design to default values.

If you want to reset individual row or column settings, use the Row menu or Column menu and select the individual settings to reset. For example to return the row height to the default value, select Row, and then select Reset Height.

40 Spread for BizTalk Developer’s Guide

BizTalk Server Administration Console

In the BizTalk Administration Console, you can modify the component settings, including setting a password. Within the component property grid in the BizTalk Administration Console, the password is displayed in its exact form. From the "Configure Pipeline" dialog for the Receive Location, you can override the password used by the component during runtime.

Note: Once an override password is specified, if it cannot be cleared to , BizTalk assumes the password override is a blank string (""). If this is not the case, the only way to reset this behavior is to reset the Receive Pipeline in the "Receive Location Properties" dialog or to reset the Send Pipeline in the "Send Port Properties" dialog.

The following image displays the Receive Location with configuration information for the Spreadsheet Disassembler component of Spread for BizTalk:

Spread for BizTalk Developer’s Guide 41

42 Spread for BizTalk Developer’s Guide

Glossary

A assembler See Document Assembler.

attribute In the schema wizard, you can set an entity to either an attribute or an element in XML. See also Select the Entity Mapping (Wizard Screen).

C code page In the schema wizard, when you select the spreadsheet file you can set the code page. The code page specifies the character set that will be used when generating the XML schema See also Select the Spreadsheet File for Schema Information (Wizard Screen). Common Language Specification (CLS) compliance For details about CLS compliance of FarPoint Spread for BizTalk, see CLS Compliance Notes. CSV (comma-separated value) file type FarPoint Spread for BizTalk can import files of this type. For more details, refer to Working with Originating Spreadsheet Files.

D data type The type of data that FarPoint Spread for BizTalk will try to coerce a set of data to; assigned in the schema as part of the entity mapping. Refer to Select the Entity Mapping (Wizard Screen). disassembler See Spreadsheet Disassembler. Document Assembler A component of FarPoint Spread for BizTalk that is added to the BizTalk send pipeline. See also Select the Entity Mapping (Wizard Screen). DocumentSchema Property of the Spreadsheet pipeline component. See schema.

E element An entity type in XML, and an option (as opposed to attribute) in the Select the Entity Mapping (Wizard Screen) entity A piece of XML, the type of which can be set to either element or attribute for a set of data. This is set in the Select the Entity Mapping (Wizard Screen). entity mapping This is set in the Select the Entity Mapping (Wizard Screen). Excel file This is the input file that FarPoint Spread for BizTalk parses and outputs XML file. See XLS file or XLSX file.

F FarPoint Spread for BizTalk

Spread for BizTalk Developer’s Guide 43

The shorter name used in this documentation for the product officially called FarPoint Spread for Microsoft® BizTalk® Server 2006. field name The designation given to the top of the column of data in the spreadsheet file that is assigned to the schema as part of the entity mapping. Typically taken from headers, if there are any in the spreadsheet file. Refer to Select the Entity Mapping (Wizard Screen).

field type The entity type (either element or attribute) for the data as it is to be assigned in the schema as part of the entity mapping. Refer to Select the Entity Mapping (Wizard Screen). format See Format Designer and Spreadsheet Format property. Format Designer Available from the Format Template property of a send pipeline, this designer allows you to customize the presentation or format of the output document. See Using the Format Designer.

forums A convenient way to get quick answers to questions about FarPoint Spread for BizTalk and to receive technical support in general. Our customer forums are available online at www.clubFarPoint.com.

H header (rows) The top row(s) in a spreadsheet file that contain(s) headings for the columns. These header rows can be ignored when selecting data. FarPoint Spread for BizTalk keeps track of header rows and uses them as default values in the field names (in the Entity Mapping screen of the Schema Wizard). See also, trailer. Refer to Select the Spreadsheet Data (Wizard Screen) and Select the Entity Mapping (Wizard Screen).

N namespace See target namespace

P PDF Portable Document Format file type for output documents in the Document Assembler part of FarPoint Spread for BizTalk. See Designing the Format for the Document Assembler. pipeline component The component in a BizTalk project to which to add the Spreadassembler or disassembler or both. See receive pipeline and send pipeline. Pipeline Properties The properties in a Visual Studio project in BizTalk that are necessary for setting FarPoint Spread for BizTalk assembler or disassembler or both. See Adding a Spreadsheet Disassembler to a Receive Pipeline.

R receive pipeline Adding a Spreadsheet Disassembler to a Receive Pipeline.

44 Spread for BizTalk Developer’s Guide

S schema The XML schema that parse the incoming Excel stream and outputs an XML stream. Refer to Selecting the XML Document Schema for the Disassembler. schema wizard See the Spreadsheet Schema Wizard. send pipeline The outgoing part of the BizTalk process in which you can automate the handling of output documents using FarPoint Spread for BizTalk. Refer to Adding a Document Assembler to a Send Pipeline. spacer (rows) The empty row(s) in a spreadsheet file that contain not data and are used typically to provide space between headers and data or data and trailers. These spacers can be ignored when selecting data. Refer to Select the Spreadsheet Data (Wizard Screen). Spreadsheet Disassembler A component of FarPoint Spread for BizTalk that is added to the BizTalk receive pipeline. See also Select the Entity Mapping (Wizard Screen). Spreadsheet Format property A setting of the Document Assembler of the send pipeline in a BizTalk project that allows you to select the output file type (XLS, XLSX, or PDF) of the output document. See Designing the Format for the Document Assembler. Spreadsheet Schema Wizard For information about the Spreadsheet Schema Wizard, that creates the XML schema, refer to Creating the Spreadsheet Schema with the Wizard.

T target namespace The XML namespace that is inserted in the header of the XML schema. For information, refer to Select the Spreadsheet File for Schema Information (Wizard Screen). trailer (rows) The bottom row(s) in a spreadsheet file that contain totals or other footer information for the columns. These trailer rows can be ignored when selecting data. See also header.

TXT (tab-delimited) file type FarPoint Spread for BizTalk can import files of this type. For more details, refer to Working with Originating Spreadsheet Files.

U unmapped entities These are XML entities that correspond to unselected data in the spreadsheet file that are not mapped to the resultant XML schema, but are persisted. See the Select the Entity Mapping (Wizard Screen).

W wizard See the Spreadsheet Schema Wizard.

Spread for BizTalk Developer’s Guide 45

X XLS file XLS is the file type for workbook or spreadsheet files made in Microsoft® Excel®. Information about XLS files in this documentation is based on BIFF8 (Binary Interchange File Format, version 8 from Microsoft) which is the file format for several versions of Microsoft Excel (Excel 97, Excel 2000, and Excel XP). If you are working with custom-created XLS files (not necessarily created in Microsoft Excel), you may want to first check with FarPoint to ensure compatibility with FarPoint Spread for BizTalk. Refer to Working with Originating Spreadsheet Files. XLSX File XLSX is the file type for newer workbook or spreadsheet files made in Microsoft® Excel® 2007 (Office 2007). FarPoint Spread for BizTalk supports this Microsoft Office Open XML (OOXML) file format for newer Excel files. If you are working with custom-created XLSX files (not necessarily created in Microsoft Excel), you may want to first check with FarPoint to ensure compatibility with FarPoint Spread for BizTalk. Refer to Working with Originating Spreadsheet Files. XML Extensible Markup Language, an international standard for encoding data and content. XML is also the file type for files created in XML. XSD The file type for an XML schema.

46 Spread for BizTalk Developer’s Guide

CLS Compliance Notes

Spread for BizTalk is built to be compliant with Microsoft's Common Language Specification (CLS). (For more background, refer to Common Language Infrastructure.)

However, there are certain non CLS-compliant .NET interfaces and objects that are required for communicating with Microsoft BizTalk Server 2006 at runtime and with Microsoft Visual Studio at design time. Because of this, there are classes and methods in the Spread component that are marked as being non CLS-compliant.

The Spread members are listed here with the reason they are not CLS-compliant.

. FarPoint.BizTalk.Pipeline.SpreadComponents.DisassemblerWizard. SpreadsheetIDTWizard.Execute method: This method is called from Visual Studio 2005 to invoke the Spreadsheet Schema Wizard. The EnvDTE.wizardResult parameter is not CLS-compliant. . FarPoint.BizTalk.Pipeline.SpreadComponents. SpreadsheetDisassembler class: This class is invoked by Visual Studio 2005 at design-time for property get/set, and from BizTalk Server at runtime. The Microsoft.BizTalk.Component. BaseCustomTypeDescriptor class is not CLS- compliant. . FarPoint.BizTalk.Pipeline.SpreadComponents.SpreadsheetDisassembler.Load method: This method is called from Visual Studio and BizTalk Server to set the properties to the component. The Microsoft.BizTalk.Component.Interop. IPropertyBag parameter is not CLS-compliant. . FarPoint.BizTalk.Pipeline.SpreadComponents.SpreadsheetDisassembler.Save method: This method is called from Visual Studio 2005 and BizTalk Server to get the properties from the component. The Microsoft.BizTalk.Component.Interop. IPropertyBag parameter is not CLS-compliant. . Microsoft.BizTalk.Message.Interop.IBaseMessage.GetNext method: This method is called by BizTalk Server after disassemble has been called to retrieve the next message from the queue. The Microsoft.BizTalk. Component.Interop.IPipelineContext parameter is not CLS-compliant and the Microsoft.BizTalk.Message.Interop.IBaseMessage parameter is not CLS- compliant. . FarPoint.BizTalk.Pipeline.SpreadComponents.SpreadsheetDisassembler.Disasse mble method: This method is called by BizTalk Server to perform the message disassembly. The Microsoft.BizTalk.Component.Interop.IPipelineContext parameter is not CLS-compliant and the Microsft.BizTalk.Message. Interop.IBaseMessage parameter is not CLS-compliant.

Spread for BizTalk Developer’s Guide 47

Getting Technical Support

If you have a technical question about this product, consult the following sources:

Online help and other documentation files installed with the product.

Product forum at http://www.clubFarPoint.com/Forums/.

If you are not a member of the forum, follow these instructions to become a member:

. Go to the forum at http://www.clubFarPoint.com/Forums/. . At the top of the page, click the Create Account link. . Read the Registration Agreement Terms and if you agree to the terms, click the appropriate link at the bottom of the page. . Complete the Registration Information (required), Profile Information (optional), and Preferences (optional) sections, then click Submit.

If you cannot find the answer using these sources, please contact Technical Support using one of these methods:

. Web site www.gcpowertools.com . E-mail [email protected] . Fax (919) 460-7606 . FTP site ftp://ftp.fpoint.com . Phone (919) 460-1887

Technical Support is available between the hours of 9:00 a.m. and 5:30 p.m. Eastern time, Monday through Friday.

48 Spread for BizTalk Developer’s Guide

Contacting Us

If you would like to find out more about GrapeCity and our products, contact our Sales department using one of the following methods:

Web site www.gcpowertools.com

North America Contact

GrapeCity, Inc. 808 Aviation Parkway Suite 1300 Morrisville, NC 27560 USA

Phone (800) 645-5913

Fax (919) 460-7606

E-mail [email protected]

Spread for BizTalk Developer’s Guide 49

50 Spread for BizTalk Developer’s Guide