Topic: Microsoft Servers. Professional BizTalk Server () cover image. Professional BizTalk Server Darren Jefford, Kevin B. Smith, Ewan. This books (Professional BizTalk Server [DOWNLOAD]) Made by PDF files, Download Online Professional BizTalk Server Professional BizTalk Server Darren Jefford, Kevin B. Smith, Ewan Fairweather. ISBN: Apr pages. Select type: E- Book.
|Language:||English, Spanish, Japanese|
|Genre:||Children & Youth|
|ePub File Size:||30.72 MB|
|PDF File Size:||11.85 MB|
|Distribution:||Free* [*Regsitration Required]|
Professional BizTalk server / Darren Jefford, Kevin B. Smith, Ewan Fairweather. As a result, Darren recently coauthored Professional Visual Studio Team. BizTalk Server also uses the latest releases of other Microsoft technologies. .. Visual Studio , an environment in which software professionals feel. BizTalk Solutions to real-world issues for BizTalk professionals panion. Available .. BizTalk Server Failed Message Routing As a Blueprint
Enter this format into the two properties. The source data store will always contain proprietary information used within the data store itself such as unique identifiers and metadata ; this data is generally not needed by external systems and should not be included in the source schema. Enterprise, or so they think it turns out later to simply be a training simulation. Begin by expanding the EDI. Essentially, the configuration consists of setting up the BizTalk party to expect that a document will be delivered from the trading partner that was just delivered to. Save the map.
The functional acknowledgment should appear as shown in Figure The final step is to set up the trading partner to receive the acknowledgments in EDI format. This is done by configuring the Trading Partner As Receiver properties.
Since acknowledgments are exactly like any other EDI document, they get their header and footer segments from what is configured in the party settings. For full details about configuring a Trading Partner As Receiver, see Exercise in the next section.
Save all of the party settings by clicking OK. However, all of the fields are required to be set in the BizTalk Administration Console before the properties can be saved. For fields such as ST01, the value can be set to anything; this value will be overridden by the EDI send pipeline with the appropriate value e. Next, set the send pipeline on the acknowledgment send port to EDI Send.
The send port was created in a previous step and is called EDI. Test the solution again, this time validating that the EDI acknowledgment documents are written out rather than the XML equivalent shown earlier: The functional acknowledgment should appear as shown in Listing ; the technical acknowledgment is shown in Listing Note that unless the name of the output file was changed, the documents will still be written out with the.
They are text files, however. This document can be any type of EDI instance, including an acknowledgment. When sending documents from BizTalk Server R2 to an external trading partner, all segments and acknowledgments related to setting a party as a receiver configured in the EDI properties of the party must be configured. This section outlines the flow of a Trading Partner As Receiver, contains an exercise demonstrating how to configure the party settings, and includes information about subscribing to any acknowledgment documents that are returned.
Figure illustrates the flow of an EDI document to a trading partner configured as a receiver. Trading Partner As Receiver Exercise Configuring a Trading Partner As Receiver Follow these steps to configure a trading partner as a receiver: In an actual implementation, these values would be set based on trading partner requirements usually defined in the EDI implementation guide provided by the partner shown in Figure ISA segment configuration settings Figure ISA interchange control header in implementation guide a.
The sender and receiver IDs are always 15 characters or less in length. Set ISA11 to U. Set the separator suffix to CR LF. Different trading partners will have different requirements around what separators are needed. Set ISA12 to This is based on the version of the standard being used for the interchange envelope. Validate ISA It will be automatically generated. This value will increment by 1 for each document that is run through the system.
ISA14 can be set to indicate whether an acknowledgment is expected. Check this box. Set ISA15 to indicate whether the data is test or production data. In this case, it is test. With the ISA segment configured, click the GS and ST segment definition and set the properties as outlined in the figures showing the sample implementation guides the GS segment is shown in Figure , and the ST segment is shown in Figure Follow these steps to configure these properties.
GS functional group header Figure ST transaction set header a. The GS6 value is automatically incremented for each document that is processed. For this exercise leave it set to the default value.
Only one row will be configured; enable the Default check box on the first row. The ST1 property should be set to — Invoice.
The Target Namespace property is set to the value of the target namespace in the schema that represents the EDI document that will be delivered to the trading partner. For this exercise, select the http: GS4 represents the format for the date, while GS5 represents the format for the time. Enter this format into the two properties. Set the value of GS7 to X. Set the value of GS8 to The setting for ST2 represents the transaction set control number.
This value can be set in a map generally to a unique identifier that can be used in the source system, BizTalk processing, and the target system or can be set to a unique value, overriding anything that may have been mapped. This can be set with the check box next to Apply New ID.
The steps in the pipeline are as follows, in the order shown: Destination party name context property matching: The pipeline tries to match the party on the exact name specified in the context property. This property will not always be set generally, it is only set by BizTalk in the case of acknowledgment generation and by code that has been entered within custom orchestrations but enables quicker processing for known types.
ID matching: If the IDs are present, the pipeline will try and match all of the IDs with a party. If no party is found with exactly the same configuration, the message will be suspended. Send port affiliation: Once the party has been resolved, the document will be sent to the send port that is affiliated with the party. If no port is associated with the party, documents will be routed based on send port filters or orchestrations that subscribe to the document.
If no filters or subscribers are configured, the document will suspend on the MessageBox. Configuring Acknowledgments Trading Partner As Receiver Exercise outlines all of the steps necessary to send an acknowledgment to a trading partner when that partner has been set up as a sender. When the trading partner is a receiver, the process is inverted.
Essentially, the configuration consists of setting up the BizTalk party to expect that a document will be delivered from the trading partner that was just delivered to. When an acknowledgment is expected from an external party, BizTalk will await a response to correlate back to the original sent message using BAM activities.
The key item to understand about acknowledgments set up for a Trading Partner As Receiver is that the trading partner returns the acknowledgment to BizTalk—just like any other document would be returned—and BizTalk must subscribe to the document and process it.
This means that a receive port and a receive location must be set up to listen to where the trading partner will return the document. Without this activity, there is no way to determine which acknowledgment is a result of which original EDI document, unless a custom orchestration has been created that manages this correlation itself. This correlation process is performed automatically by the BizTalk engine.
Figure illustrates the full cycle of the acknowledgment and the creation of the BAM activity. As soon as the acknowledgment is returned, the trading partner must be viewed as a sender, and the document must be subscribed to by a BizTalk receive port to be processed. Make sure and refer to Exercise for an in-depth look at configuring acknowledgments and configuring the BizTalk components.
Sample implementation of acknowledgment flow from receiver Configuring AS2 Properties The discussions and exercises up to this point have dealt with parties configured to handle EDI documents delivered via traditional file-based transmission methods FTP, email, file, etc. Acting as an envelope containing the traditional EDI document, AS2 provides additional layers of security with capabilities around document encryption and contains information about how to resolve a document against a party.
The purpose of this section is to introduce the concept of AS2 and how it is related to a trading partner, but not to introduce information specifically related to the actual delivery of the document using this protocol. A full description of how to use the standard AS2 functionality that ships with BizTalk, and how to work with a third-party AS2 adapter, is described in detail in Chapter 5. The key differences in processing EDI documents delivered using AS2 are that the AS2 EDI pipelines are used rather than the standard EDI pipelines referred to up to this point and that the majority of transmissions are encrypted through the use of certificates.
Documents are resolved to parties based on what is entered into the alias of the party this is largely ignored by standard EDI transmissions. Before documents can be resolved, they must first be decrypted using certificates stored in the certificate store external to BizTalk.
In the window that opens, there are three basic tabs: Properties that are related to the transmission, but that cannot be set in the adapter, are set within the party properties.
When an AS2 transmission is sent to BizTalk, it is generally encrypted using a certificate. The properties on this screen allow the user to configure the appropriate way to decrypt the incoming document and how to send the Message Disposition Notification MDN acknowledgment back to the sender. It is used primarily as a receipt to eliminate any argument that the transmission was received.
When BizTalk initiates the AS2 transmission, the party is the receiver of that transmission. The properties around how to sign and encrypt the message, which only the receiver knows how to decrypt, are set on the Party As Receiver tab.
The most important settings on this tab include configuring whether MDN acknowledgments are expected back and the settings for AS2-To and AS2-From which correspond to what is configured for the party alias, as shown in Figure AS2 uses aliases in party resolution standard EDI largely ignores aliases.
For example, certificate resolution may be configured directly on the third-party AS2 adapter, whereas the standard BizTalk AS2 functionality sets certificate resolution on the party.
AS2 properties Validating Trading Partner Settings One of the most elusive portions of EDI documents is viewing and validating the header, context, and footer information set based on how the party is configured. In most cases, this information is only available once the document has been fully processed, run through the EDI send pipeline, and delivered to an external location.
This section outlines how the header, context, and footer are added to the document and demonstrates with Exercise the full validation process. As BizTalk routes messages EDI or otherwise around, there is the message the body , and all of the context information about that message such as where the message first came from, its schema, any promoted fields, etc.
Not until the EDI document is sent through an EDI pipeline do the header and footer information actually become part of the document. Because of this, it is not possible to see the full EDI document as it would appear to an external trading partner until the document has been fully sent through an EDI send port. To illustrate the message body vs. This is prior to being processed by the EDI send pipeline. All of this information is accessed via the BizTalk Group Hub on a suspended message details of using the Group Hub and working with messages appears in Chapter 6.
Message body showing content prior to processing by EDI send pipeline Exercise demonstrates the minimum number of components needed to create a full EDI file instance. The components that are built can be used for any EDI document and are generic enough that they could be set up at the beginning of an EDI development project and reused throughout the project to validate documents.
The contents of the document will not contain valid data, but the header, detail, and footer information will be valid. This exercise will walk through creating a sample XML instance, a receive location where this instance can be dropped, and an output location where the EDI output will be written. Figure outlines the flow of a document through the components of this exercise. Validating trading partner settings exercise flow 1.
Begin by creating the BizTalk application and deploying the schema, using these steps: Open the solution file Apress.
This contains one schema that will be used for demonstration purposes. Deploy the schema project by right-clicking the project and selecting Deploy. This will deploy the schema to the EDI. Chapter2 BizTalk application. The application will be created if it does not already exist. Next, create a sample instance to work with. A version of this has been created in C: Right-click the schema in Visual Studio and select Properties.
In the window that opens, set the Output Instance Filename to a valid directory on the local computer. Right-click the schema again and select Generate Instance.
Validate that the sample instance is written to the specified location. Create a receive adapter and a file receive location where the sample XML instance will be dropped by working through these steps: Give the receive port a name for this demonstration, it is named EDI. Click the Receive Locations tab and click the New button. A fully configured receive location is shown in Figure Name the receive location the sample is named FileReceive. The demonstration has it configured at C: Configure file receive location 4.
Create a file send adapter that will listen for documents coming in on the receive port created in the previous step and will run them through the EDI send pipeline, converting the XML into an EDI document and adding the header, detail, and footer information configured for the trading partner by working through these steps: Name the port appropriately.
This exercise uses EDI. Set the type as FILE and configure an appropriate output folder and file name: Set the output folder for this exercise as C: This will force all documents received by the receive port to be routed through this send port. See Figure Send port filter f. Click OK to save the port settings.
Enlist and start the send port and the receive location created in the previous steps. This can be done by rightclicking the object and selecting Start. Tie the trading partner to the send port.
Using the trading partner created in Exercise and configured in Exercise , double-click the party Company X and ensure that the send port created appears in the send port list ports can be selected via drop-down under the Name column, as shown in Figure Tie send port to trading partner 7.
Look for the output document in the file directory configured for the output location. The header, detail, and footer information will be visible as shown in Listing , and can be compared to the expected settings for the trading partner. If the document does not appear, check the Windows Event Viewer for error information. This chapter looked in detail at setting up trading partners and working with acknowledgments.
The process begins with determining whether the trading partner settings should be based on the EDI implementation guide if one exists. Setting the header and footer segment information is the first step, regardless of whether the partner is a sender or a receiver. After this has been configured, any needed acknowledgments should be set up. Depending on the flow of the document, send or receive ports will need to be prepared to be able to deliver the acknowledgments back to the partner.
If an EDI document is being transported using AS2, additional properties must be configured on the party. The chapter concluded with an overview of how to validate and test that the BizTalk party has been configured correctly by demonstrating how to output a full EDI document with header and footer information included within it.
The goal of this chapter is to introduce a logical approach to determining how to define and structure the source and target data, how to retrieve the source data and deliver it to BizTalk Server, how to map the source data to the target trading partner schema, and how to test that the map produces the expected an EDI text file.
The following topics are covered in this chapter: Mapping includes three primary BizTalk components: With the components defined, the source data must be returned to BizTalk Server for processing. The actual mapping of data from the source schema to the target schema is done through a combination of analyzing business requirements determining how fields are related in the source and destination schemas and implementing the logic to accomplish this through actual map development.
Generally, mapping requirements are outlined in the EDI implementation guide supplied by the trading partner. The section on mapping covers in detail some of the more common mapping tasks for EDI documents. Throughout the development process, the map will need to be tested. This section outlines a step-by-step approach to testing EDI maps and understanding how to correct errors that may be encountered. Preparing the Solution Files The exercises in this chapter assume a general understanding of EDI schemas and trading partner configuration.
The first exercise Exercise introduces how to set up the sample code files that accompany this book, for use in later exercises.
Preparing the Solution Files The exercises in this chapter use the solution files located in Apress. Use the following steps to deploy the solution files to a local machine: Open the solution file in Visual Studio on the local computer.
The solution file contains two projects: This project contains the source data schema and is placed into a separate project so that it can be referenced by any trading partner project. Add the database to SQL Server. There are two options for creating the database this assumes the use of SQL Server The database and log file can be attached using the following steps.
This is the only option to obtain the full database with all test data populated: Right-click the Databases folder and select Attach. In the window that opens, click the Add button and browse to the location of the MDF file. It is located in the folder Apress. Alternatively, the SQL scripts can be run no data will be included. There are a total of six scripts, all contained in the folder Apress. In addition, there are two versions of the target schema and target map for Company X.
The modified map and schema as used in Exercise are located in the folder Apress. Finally, there is a sample document located in Apress. The content of this represents what is returned by the stored procedure.
The contents can be modified using a text editor. Defining the Mapping Components The first step in the process of document mapping is to determine the flow of the document s being mapped.
This includes defining where the source data is coming from, how it will be retrieved and delivered to BizTalk, what the format of the data will be, and what the target schema or schemas, in the case of multiple trading partners will be. Figure gives a high-level overview of the document flow that is covered in detail in this chapter. Many nodes in the schema that are not needed by the trading partner have been removed.
This not only simplifies the document for illustration purposes but is good practice when preparing a schema for an actual implementation. It is a necessary step to make modifications to the schema where necessary. For instance, a trading partner may be using a specific segment to contain data that does not commonly belong there. The schemas should be modified on a per-partner basis, and should generally include only those nodes that the trading partner is interested in.
Always refer to the EDI implementation guide when working with mapping requirements. Company X represents the trading partner to which EDI documents will be delivered.
The sample EDI document being used for demonstration purposes has been greatly simplified but represents a valid version of an X12 invoice document. The document shown in Listing is a sample instance of the final EDI document that will be delivered to the trading partner Company X after each of the components in this chapter is put into place.
Configuring these segments is covered in Chapter 2. It will prove to be helpful to define the target document an actual instance of what is to be delivered to a trading partner prior to creating or modifying the target schema.
Working with the trading partner to determine the format and content of the document is essential in the early stages of requirements gathering and will eliminate a great deal of work during the development stage.
Company X will use a modified version of the standard schema, as shown in Figure Trading partner target schema modified from standard schema Defining the Source Data and Schema The source data is defined as all data being extracted from the source data store.
It includes all data needed by any trading partner, such as billing and shipping address data, details about the contents of a message e. It also includes all data that may be used during processing by BizTalk Server such as IDs for tracking and any other data that may be extracted—used or unused.
This data may come from multiple sources, or it may come from a single source. For successful mapping, it is essential to define what the source data is, where it is coming from, and what the delivery format will be.
For the purposes of this section, the source data will come from a single data store SQL Server and from a sample database that is intended to mimic a fractional subset of information housed in an accounting application.
From this data, invoices will be generated, resulting in EDI documents. In some rare instances, all of the needed data is known at the start of the project, and the complexities of defining where the data comes from are greatly diminished.
In either case, whether the data is fully defined or whether it is being defined in parallel with development, implementing the structure of the data and encapsulating it into a source schema is a task that requires a great deal of thought to ensure that the longterm requirements of the trading partners are met.
The creation of the source schema begins with determining how best to structure the data. This is most easily accomplished by assessing how the data is set up in the source data store i. In the case of the sample implementation, the source database is structured as defined in Figure With the data model of the source database known, and the target EDI document schema defined, the next step is to determine which of the fields are of interest to the external systems including BizTalk and its components: The source data store will always contain proprietary information used within the data store itself such as unique identifiers and metadata ; this data is generally not needed by external systems and should not be included in the source schema.
For the sample implementation, the proprietary information includes most of the GUIDs e. It is intended to be used for tracking purposes within BizTalk Server.
No trading partner is typically interested in this type of data, but it often makes sense to include it to be able to track the document through BizTalk. Source database diagram From understanding the database diagram what data is available and knowing the target trading partner data requirements what data is needed , it can be determined that the source document schema should be as shown in Figure Common source schema Retrieving the Source Data This section outlines an approach to retrieving the data from the source data store, which will simplify schema development and the delivery of data to BizTalk Server.
As with all integration projects, there are a large number of potential options in retrieving data that depend on a variety of factors: Different data stores have different methods for accessing the data they contain. This may be via stored procedures, web services, a custom API, flat files, or a number of other objects. The amount of information in a transaction, whether data will be batched or handled as individual transactions, and the size of data transmissions can have an impact on how the data will be retrieved or delivered.
The frequency that data will be transmitted to BizTalk Server and whether this data will be delivered asynchronously or synchronously real time will help determine how best to implement the retrieval of source data.
If two-way communication needs to occur between the source system and BizTalk Server i. Occasionally the data store may be on a portion of the network that is not directly accessible to BizTalk Server. Security restrictions may require different approaches to retrieving data from the source. For the purpose of discussion and demonstration, this section outlines the most common form of data retrieval from a data source housing EDI data: From this process, more complex patterns can be implemented to suit the needs of any EDI implementation.
The database component outlined here is the stored procedure, which returns the result set as an XML document. Rendering result sets in XML within the stored procedure rather than trying to work with schemas on the SQL Receive Adapter to format the result sets after receiving the data simplifies the data retrieval process, making the delivery of the data to BizTalk Server as seamless as possible.
A number of enterprise-level databases support some level of XML retrieval, and the approach outlined in this section can be used to process data directly from these systems. In many cases, the simplest approach to retrieving data from any external data source is to use linked servers from SQL Server , which allows full flexibility in the stored procedure on SQL to process data on external databases. The function of the stored procedure is to return all of the fields needed in the creation of the target EDI schema.
The stored procedure outlined in Listing retrieves an XML document that matches the source schema defined earlier see Figure A sample instance of the XML document that will be generated by the stored procedure is shown in Figure In this case, the root node in the schema is , while the root node retrieved by the stored procedure is.
The node will be automatically added by the SQL Adapter. Remaining documents will be processed -- on subsequent calls to this stored procedure. It can be configured to run on a timed interval and will continue to call the stored procedure until all available invoices have been returned the stored procedure shown in Listing returns a single document each time it is called.
The steps outlined in Exercise provide all of the information needed to configure the SQL Adapter to return the result set in the format that matches the source data schema shown previously in Figure Chapter3 application or the application that contains the BizTalk components.
On the General tab, name the port appropriately the sample implementation names this EDI. Click the Receive Locations tab. In the right-hand window, click New to create a receive location.
Name the receive location appropriately in this case, SQLReceive. The name will distinguish it from other receive locations that may be associated with this port. Next to Type, select SQL.
Click the Configure button. Figure shows the window with each of the properties set in the following steps. Configuring the SQL receive location properties a. Poll While Data Found: This indicates whether the adapter will continue to call the stored procedure until no results are returned, or whether it will only be called once per execution period. For this solution, set this value to True.
Each time the stored procedure is called, only one document will be returned. By setting this value to True, the procedure will continue to execute until all documents have been returned to BizTalk. Depending on how the stored procedure is written, this may pose a problem. For instance, in the procedure called in this exercise, a flag is set indicating that a row has been delivered after the data has been returned.
If the stored procedure is to be called simultaneously by multiple servers in a BizTalk Group, the result set may be returned more than once due to the fact that the flag will not be updated in time to prevent the second call from retrieving the same record.
In a case such as this, the Poll While Data Found would need to be set to False, or a more robust way of determining whether data has already been retrieved would need to be added to the stored procedure. Polling Interval: This setting indicates the amount of time to wait between executions of the stored procedure.
The time will depend on the number of documents being returned and the frequency that these documents become available. For this demonstration, set the value to Polling Unit of Measure: Units are Hours, Minutes, or Seconds. Set this to Seconds. Connection String: This is the connection string to the database where the stored procedure exists. Click the ellipsis to configure this setting. Once the values have been set, click the Test Settings button to ensure that the values are valid.
Note that allowing the password to be saved will ensure that when exporting to an MSI file, the password will be stored.
If it has not been saved, it will have to be set when imported to a new environment. Document Root Element Name: This is the root element of the schema that the document being retrieved will adhere to. The root node of the document being retrieved by the stored procedure will be wrapped by this node. Document Target Namespace: This value must match the target namespace of the schema that the document being retrieved is set to.
To find this value, open the schema in Visual Studio and find the Target Namespace property. For this solution, set the value to http: SQL Command: When calling a stored procedure that returns a formatted XML document, all that needs to be set for this property is the SQL command to execute the stored procedure. In this case, set the value to exec spGetInvoice.
The URI identifies this document from other documents. This must be a unique value and can generally be set to the default value that the receive location will be set to automatically. Even though this is set automatically, ensure that this value is unique when there is more than a single SQL receive location.
For this solution, this property should be set to SQL: Note that each time this property comes into view when the window is opened BizTalk may automatically reset it to the default value.
Make sure each time the SQL Transport properties are viewed or modified , this value is set to the correct value. On the Schedule tab, configure the receive location to execute during the appropriate hours.
For example, there are frequently database backups that run during the early morning hours, networks are occasionally offline for maintenance, and so on. It may be appropriate to force the processing of documents to occur only during business hours. For this solution, the receive location will always be turned on no modifications to the schedule are necessary. All values have been configured to call the stored procedure and return an XML document.
Later chapters will discuss exception handling and tracking options. Implementing Linked Servers Generally speaking, data is stored in an enterprise-level database, which may or may not be SQL Server In cases where this is not SQL , it is possible to use the same model discussed in the previous section, by implementing linked servers. Exercise outlines the modifications that need to be made to the stored procedure shown in Listing to allow it to interact with a linked server.
There are some limitations to linked servers that should be looked at prior to implementing them in a solution—most importantly, the increased demand on the network for the traffic generated between the database that houses the stored procedure and the database that is being linked to. For many EDI implementations, documents are retrieved from source systems on timed intervals perhaps once a day, hourly, etc.
In other cases, where large numbers of documents may be returned on a very frequent basis, it will likely make more sense to develop an interface directly between BizTalk Server and the source data store such as through the use of a custom adapter.
For purposes of discussion here, it is assumed linked servers will fulfill the requirements. Figure depicts the components used when retrieving XML data from a linked server. Retrieving data using XML and linked servers Exercise Using a Linked Server The following steps indicate how to add a linked server to SQL Server and how to modify the stored procedure created earlier in this chapter see Listing to interact with this linked server instead of with tables on the same database as the stored procedure: Name the linked server this is how it will be referred to in the stored procedure and configure all of the details about how to connect to it on the General tab.
For this exercise, the name will be TestLinkedServer. On the Security tab, indicate how to connect to the target system. This should be set to use the same BizTalk account as is configured to run the SQL Receive Adapter; when the stored procedure executes, it will run under the context of this account. In turn, the linked server connection will impersonate this account. Right-click the BizTalkServerApplication account and select Properties to see how this account has been configured.
Once the linked server has been set up and verified, the stored procedure must be modified to be able to interact with it. This is a very simple modification, consisting primarily in changing the table names to the full linked server table name. Take the following steps: Add a new command at the top of the stored procedure as follows. This will ensure that connections to the linked server are handled properly: Mapping requirements can be simple or complex, depending on the requirements outlined in the implementation guide or defined by the trading partner.
In some cases, it may be as easy as dragging the source element and dropping it on the target element. In other cases, it may be more involved, requiring custom functoids, external. NET assemblies, and lookup tables. In any case, simple or complex, some amount of logic will need to be put into place to ensure that the document is mapped correctly.
This section outlines some common tasks that may be encountered during the mapping of EDI documents.
Exercise walks step-by-step through the creation of the map, including the configuration and placement of functoids. Before working through the exercise, however, it is important to look at several items.
When mapping EDI documents, keep the following in mind: Information about the target element can be obtained from one of the properties on the target schema: This property can be useful when trying to determine what different elements represent, as it describes the expected content of the node. When configuring any functoid, ensure that the input fields are in the correct order. For example, when using a value mapping functoid, the first parameter must always return a boolean value, while the second parameter should always represent the value to be mapped when the boolean value is True.
For tracking purposes, it is very useful to take a unique document identifier from the source system and map it to this field; this way, the document can be tracked from the source system, through BizTalk Server, to the document that is delivered to the trading partner. However, in some cases it may make more sense to have BizTalk override this with a unique ID that is automatically generated by the system. These counters can be complex to calculate when there are line items in the source document that are not mapped, and therefore not counted.
In simple cases, when all line items are mapped from the source document to the target document, an iteration functoid or record count functoid could be used to set these values. But in cases where there are unmapped line items, a global variable in the map is useful. A global variable allows a counter to be set and incremented for all items that are mapped, ignoring unmapped values.
Listings and are used in the functoids included in the calculation of the IT and CTT01 elements. The code in Listing shows how to set and increment a global variable in a map each time the script functoid that the code is contained within is executed. In Exercise , this value is used in the IT element for each line item that is mapped. It is based on the EDI implementation guides shown in the figures throughout this exercise: Open the Visual Studio solution. For this exercise, open Apress. To add a new or existing map, right-click the project to which the map will be added.
In this example, right-click Apress. In the window that opens, click Map Files and select Map from the right-hand window. This will add a new map to the project. Browse to the location of the map, select it, and click Add. This will add an existing map. The rest of this exercise assumes that the map does not already exist. Once the new map is added, make sure that it is open in Visual Studio.
Two links will appear: To add the source schema, click Open Source Schema. In the BizTalk Type Picker window that opens, select the document that will be the source schema. Because this solution uses a separate project to store the source schema, it appears under References. This will set the source schema for the map. To add the target schema, click Open Destination Schema. This sets the target schema for the map.
Map the fields according to the trading partner requirements, as shown in these steps: All maps are created with a single tab. To aid in organizing a complex map, rename this tab to ST. Additional tabs will be created for different EDI document segments. The ST segment is known as the transaction set header.
The map for the ST segment is shown in Figure and is based on the requirements outlined in the implementation guide shown in Figure Mapping the ST segment Figure Drag and drop a Concatenate functoid onto the map surface. Double-click the shape and set it to Connect it to the ST01 node in the target schema.
This segment indicates the Transaction Set Identifier Code, which in this case is the same as the document type. This is the unique document ID transaction set control number that can be used to identify a document in the source system, throughout BizTalk Server components, and with the trading partner once the document has been delivered. Create a new tab on the map for the N1 loop.
Right-click the ST tab at the bottom of the map surface and select Add Page. Name the new page N1 loop. The N1 loop contains segments with name, address, and other company contact information. Refer to Figure and Figure for the mapping specifications.
The final map is shown in Figure N1 segment mapping details Figure N4 segment mapping details Figure N1 loop: The following steps ensure that no subnode to the N1 loop will be mapped in the target element unless the address type is appropriate: Drag and drop an Equals functoid onto the mapping surface. Double-click the Equals functoid and create a constant value of Billing.
Drag the output of the Equals functoid to the N1Loop1 node on the target schema. Drop a Concatenate functoid on the map surface. Set the value of this functoid to ST. Drag the output of this functoid to the N node in the target schema. This represents the entity identifier code. This represents the name of the trading partner. This represents the city name. This represents the state name. Drag the source element ZIP to the target N element. This represents the postal code.
Because the data in both is closely related, some of the functoids will be used to generate data for multiple elements. Right-click one of the page tabs at the bottom of the map and select Add Page. The IT1 loop represents line item information, while the CTT loop contains information about the total transaction summed from line items.
The specification for the IT1 loop is shown in Figure The CTT loop will be covered in later steps in this exercise. IT1 segment mapping details i. IT1 loop: The following steps will ensure that only valid line items are mapped: Drop a Scripting functoid on the mapping surface.
Right-click the functoid and select Configure Functoid Script. Select Inline C for the Script Type property. Enter the code in Listing into the script window as shown in Figure Empty; break; default: Inline script for item type scripting functoid 5.
Click OK to save the code for the scripting functoid. Drop an Equals functoid on the mapping surface, to the right of the Scripting functoid. Right-click the Equals functoid and set a constant value of Map. Drag the output of the Scripting functoid and drop it on the Equals functoid. Drag the output of the Equals functoid and drop it on the It1Loop1 node in the target. This element represents the identifier for the line item. Figure shows the mapping for the IT1 loop.
Mapping the IT1 loop segment 1. Drop a Scripting functoid on the mapping surface to the right of the Equals functoid. Enter the inline C code in Listing for the scripting functoid. This will ensure that the line item is only incremented for valid line items. Make the input for the Scripting functoid the output of the equals functoid. Map the output of the Scripting functoid to the target schema element IT This represents the quantity invoiced.
This element is the unit price. Using the same tab, the CTT mapping will now be added. Refer to Figure for the implementation. CTT segment mapping details v. This represents the total number of line items that are mapped in the IT1 loop.
This must be a total of only valid line items i. Drop a Scripting functoid on the mapping surface and enter the inline C code shown in Listing This represents a total of all line items. Some line items may indicate more than a single item as the quantity; therefore quantity and price are a factor in calculating this field. Drop a Multiplication functoid on the mapping surface. Drag and drop two inputs to this functoid in any order from the source schema: Drop a Value Mapping functoid on the map surface, to the right of the Multiplication functoid and to the right of the Equals functoid created for the IT1 loop.
Validate that the output from the Equals functoid is the first input parameter, as it is a boolean value. Drop a Cumulative Sum functoid on the map surface to the right of the others. The input to this functoid is the output of the Value Mapping functoid. The cumulative sum is a total of all line items mapped in the IT1 segment.
All of the mapping steps have been completed, and the map is ready to be saved and tested. Save the map file in Visual Studio. Testing the Map Throughout the development of the map, it is essential to test the output. For the majority of mapping development, all map tests can be done within the Visual Studio environment. Working in Visual Studio, it is easy to test the map, giving a sample input instance and generating the output document.
This section provides a detailed exercise demonstrating how to test the map created in the previous section. There are several fields that have been configured to fail in the exercise just completed when testing the map. This is to demonstrate how to find and fix errors during testing. The errors occur on the following nodes: The target schema has a restriction on this field that requires that it is a valid currency value two decimals or less. A functoid will be used to solve this issue.
The target schema indicates that this should be a two-character code indicating the state or province. The source data contains the entire name of the state and is a standard string. The trading partner requires that the entire string be passed in the EDI document. The target schema will be modified to solve this issue. The document shown in Listing is a sample instance of a result set returned by the stored procedure configured earlier in this chapter. Testing a map is most easily done when using a valid input document it can be done with an automatically generated instance, but this often does not adhere to valid data.
This is why defining the source data and putting into place the components for retrieval are done before beginning any mapping development. Exercise demonstrates how to test a map. Open the Apress.
EDI solution that contains the Visual Studio map created in the previous section. This can be found in the sample files at Apress.
Build the solution in Visual Studio right-click the solution and select Build Solution. In the Apress. Begin with an XML output that is not validated. The map property page with initial configuration 4. Set the TestMap Input Instance to a valid source document. This is the document that is returned by the SQL Server stored procedure, along with the root node that wraps the document when the SQL Adapter retrieves the document.
See Listing for a valid instance, or open an actual instance from the sample files at Apress. Click OK to save the settings and close the window. Right-click the map and select Test Map. This will generate a nonvalidated XML instance of the map output. The output box will display a link to the output document. The output document can be viewed by holding the CTRL key and clicking the link next to the output: Figure shows the instance as it appears after clicking this link.
Test map output in XML 7. With the output visually validated i. Right-click the map and select Properties. Click OK, right-click the map again, and select Test Map. This time an error is thrown.
There is invalid data in the N node. In this case, there are three options for solving this mapping issue: Change the source data: Instead of extracting the string from the database exactly as it is stored, logic could be implemented in the stored procedure to return the data in a two-character code. Change the map: Logic could be put into place in the map to convert the full string to a valid two-character string.
Change the target schema: Depending on the requirements of the trading partner, it may be that the best place to change the requirement is in the target schema. Remove the restriction from the N element and save the schema. For this exercise, the approach that will be taken is to modify the target schema. In the case of the trading partner, Company X, the entire string denoting the state is required i.
The steps for modifying the target schema are as follows: Expand the N1Loop1 node and click the N4 element N The properties should be displayed automatically. If they are not visible, right-click the element and select Properties. Change the Length property to nothing— remove the 2.
Save the schema.
This allows any length of string to be present in the element. Rebuild the solution right-click the solution and select Rebuild Solution. There is no need to do anything with the information in this window. It will be used later in this exercise. If a dialog appears indicating that the destination schema for a map has changed, click OK. Retest the map. Two additional errors occur; this time on the IT node.
The error indicates that the current value has too many decimal places and is not recognized as a valid value in the target schema. Again, there are three options in solving this issue: The data is stored in SQL as a data type of Money and automatically sets four decimal places. The stored procedure could be modified to return two decimals or round to the nearest dollar.
However, by fixing this in the stored procedure, the data will be extracted the same for all trading partners. Upcoming SlideShare. Like this presentation? Why not share! An annual anal Embed Size px.
Start on. Show related SlideShares at end. WordPress Shortcode. Published in: Full Name Comment goes here. Are you sure you want to Yes No. Be the first to like this. No Downloads. Views Total views. Actions Shares. Embeds 0 No embeds. No notes for slide. Book details Author: Darren Jefford Pages: