here Client Company Name T-CONNECT EDI VIEWER Installation and User Guide 12/16/2014 DOCUMENT CREATED BY: Tallan BizTalk Development Team WE BUILD SOFTWARE THAT HELPS OUR CLIENTS GROW
Table of Contents OVERVIEW... 3 INSTALLATION... 4 STEP 1: RUN THE MSI... 4 STEP 2: IN SETUP SCREEN PRESS NEXT... 4 STEP 3: READ AND ACCEPT THE LICENSE AGREEMENT... 5 STEP 4: SELECT THE INSTALLATION FOLDER AND PRESS NEXT... 5 STEP 5: CLICK INSTALL... 6 STEP 6: CHECK START DEPLOYING TO BIZTALK WHEN I CLICK FINISH AND CLICK FINISH... 6 STEP 7: SPECIFY SERVICE ACCOUNT... 7 STEP 8: CHOOSE THE ENVIRONMENT SETTINGS FILE... 7 STEP 9A: CHOOSE WHETHER TO DEPLOY 837P... 8 STEP 9B: CHOOSE WHETHER TO DEPLOY THE 837I... 8 STEP 9C: CHOOSE WHETHER TO DEPLOY THE 837D... 9 STEP 10: CLICK FINISH... 9 STEP 11: CONFIGURE THE PIPELINE COMPONENT... 9 UTILIZING THE EDIVIEWER IN BIZTALK APPLICATIONS... 13 API REFERENCE AND EXAMPLES... 14 PRE-REQUISITES... 14 METHODS... 14 EXAMPLES... 14 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 2 of 16
OVERVIEW This document outlines the process of installing, configuring and using a 30 day evaluation version of the T-Connect EDI Viewer. The EDI Viewer provides a sample application with a BizTalk pipeline component and a.net helper library primarily meant for BizTalk applications. It provides an API for converting EDI messages into a human readable PDF format. The included license will grant you use of the tool for 30 days. After that, continued use will result in an error in the Event Log stating License expired. You can extend the license of this tool at any time. Contact BizTalk@Tallan.com to inquire. SUPPORTED TRANSACTIONS At this time, the following transactions are supported: - HIPAA EDI 834 v. 5010 (root node X12_00501_834) - HIPAA EDI 837P v. 5010 (root node X12_00501_837_P) - HIPAA EDI 837I v. 5010 (root node X12_00501_837_I) - HIPAA EDI 837D v. 5010 (root node X12_00501_837_D) 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 3 of 16
INSTALLATION STEP 1: RUN THE MSI STEP 2: IN SETUP SCREEN PRESS NEXT 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 4 of 16
STEP 3: READ AND ACCEPT THE LICENSE AGREEMENT STEP 4: SELECT THE INSTALLATION FOLDER AND PRESS NEXT 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 5 of 16
STEP 5: CLICK INSTALL STEP 6: CHECK START DEPLOYING TO BIZTALK WHEN I CLICK FINISH AND CLICK FINISH 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 6 of 16
STEP 7: SPECIFY SERVICE ACCOUNT STEP 8: CHOOSE THE ENVIRONMENT SETTINGS FILE 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 7 of 16
STEP 9A: CHOOSE WHETHER TO DE PLOY 837P If you have not previously deployed the 837P schema to BizTalk, check the box off; otherwise, leave it unchecked. If you re not sure, leave the box unchecked and try the sample 837P file; if there is an error in the EventLog from the BizTalk Server EDI source with a message like Finding the document specification by message type failed, undeploy and redeploy the application with the 837P schema. Alternatively, the schemas can be deployed and later removed through the BizTalk Server Administration Console if they cause conflicts. STEP 9B: CHOOSE WHETHER TO DE PLOY THE 837I See above. In this example screen shot, the box is checked, indicating that the 837I schema has not already been deployed and that the installer should deploy it. 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 8 of 16
STEP 9C: CHOOSE WHETHER TO DEPLOY THE 837D See 9A and 9B for explanation. STEP 10: CLICK FINISH STEP 11: CONFIGURE THE PIPELINE COMPONENT The installer deploys the Tallan.TConnect.EDIViewer application, which contains a pipeline that will perform EDI conversions on the supported transactions. It also will optionally deploy the schemas for supported transactions using the default namespace for these schemas (http://schemas.microsoft.com/biztalk/edi/x12/2006), which is required for conversion; if any schema has already been deployed to BizTalk Server using the same namespace, use the options in the installer (see Steps 9A-9C) to skip deploying it. 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 9 of 16
The application s default configuration is to receive files at the C:\BizTalkPorts\TConnectEDIViewer\IN file location, write PDFs to the C:\temp directory, and output the EDI transactions (as XML) to the C:\BizTalkPort\TConnectEDIViewer\OUT file location. If the C:\temp directory does not exist (or the BizTalk service account does not have write access to it), the component will fail; ensure that the directory is created with write access for the BizTalk service account or another suitable directory is specified before using the component (the installer does not attempt to create this directory). The sample pipeline can be used in other applications by creating a reference from the existing application to the Tallan.TConnect.EDIViewer application. To configure the pipeline component, go to the Receive Locations for the Tallan.TConnect.EDIViewer application in the BizTalk Administration Console. Open the properties of the Receive Location. Click the Receive Pipeline Properties button (see next page): 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 10 of 16
Scroll to the bottom of the Pipeline Properties windows to view or alter the properties: (see next page for configuration table) 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 11 of 16
Use the following configuration table to properly configure the component: Property Name Purpose Default Value Required? Enabled Turns the component on or off True N/A (only true or false possible) Filename Specifies the output file name. The following macros are converted: %SourceFileName% %MessageID% %datetime_bts2000% (UTC yyyymmddhhmmsss) %datetime% (UTC yyyy-mmddthhmmss) %datetime.tz% (local yyyy- MM-dd-TTHHmmsszz), %time% (UTC HHmmss) %time.tz% (local HHmmsszz) %SourceFileName% _%MessageID%.pdf No; %SourceFileName%. pdf will be used as default, or %MessageID%.pdf if SourceFileName cannot be determined. Note that.pdf is not automatically appended if this value is filled in. OutputDirectory Sets the director to write output PDF files to C:\temp Yes; if directory cannot be found, error will be written to the EventLog SuspendOnError If set to true, errors/exceptions in the component will cause the BizTalk message to suspend. False N/A (only true or false possible) VerboseLogging If set to true, informational logging will be written to the EventLog. True N/A (only true or false possible) 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 12 of 16
UTILIZING THE EDIVIEWER IN BIZTALK APPLICATIONS The library can be used by BizTalk Orchestrations or by other.net helper libraries. The first step to utilize its functionality is to add a reference to the library. Open the Add References dialog and start typing EDIViewer in the search box. Highlight the EDI Viewer component and fill in the check box. Alternatively, you can add a reference by browsing to the DLL in the installation directory. The DLL uses the namespace Tallan.TConnect.EDIViewer. 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 13 of 16
API REFERENCE AND EXAMPLES PRE-REQUISITES The library has a few requirements to be able convert a message. 1. The message must be a supported transaction type. The BizTalk Message Type can either be the schema for one of those transactions (i.e. a strongly typed message) or a System.Xml.XmlDocuemnt. 2. The message must be in namespace http://schemas.microsoft.com/biztalk/edi/x12/2006. That is the default namespace used for these EDI transactions in BizTalk. METHODS The library exposes several methods for use in BizTalk applications. These methods are available in the Converter class. 1. List<string> SupportedTransactions(): returns a list of supported root nodes. 2. bool IsTransactionSupported(string messagetype): returns true when the MessageType provided (from the BizTalk context property, e.g. http://schemas.microsoft.com/biztalk/edi/x12/2006#x12_00501_837_p ) is supported by the converter. 3. void AssignPdf(string xmldocsource, XLANGMessage destination): Generates a PDF from the XML in the first argument using the MultiEdiXmlToPdf method and assigns the ZIP file to the BizTalk message in the second argument. Use this method if your source message is of type System.Xml.XmlDocument. 4. void AssignPdf(XmlReader reader, XLANGMessage destination): Generates a PDF from the XML in the first argument and assigns the PDF to the BizTalk message in the second argument. Use this method if your source message is of type System.Xml.XmlDocument. 5. void AssignPdf(XLANGMessage source, XLANGMessage destination): Generates a PDF from the message in the first argument and assigns the PDF to the BizTalk message in the second argument. Use this method if the source message is set to one of the supported BizTalk schemas. The second message should be a System.Xml.XmlDocument message. 6. void SavePdfToFile(string xmldocasstring, string uri): Generates a PDF file from the XML string and writes it directly to the specified path (uri). This function is more performant than the AssignPdf functions, providing you do not need to do any further BizTalk processing of the PDF message or leverage BizTalk s send port adapters. 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 14 of 16
7. void SavePdfToFile(XmlReader reader, string uri): Generates a PDF file from the message in the first argument writes it directly to the specified path (uri). This function is more performant than the AssignPdf functions, providing you do not need to do any further BizTalk processing of the PDF message or leverage BizTalk s send port adapters. 8. void SavePdfToFile(XLANGMessage source, string uri): Generates a PDF file from the message in the first argument writes it directly to the specified path (uri). This function is more performant than the AssignPdf functions, providing you do not need to do any further BizTalk processing of the PDF message or leverage BizTalk s send port adapters. 9. MemoryStream SingleEdiXmlToPdf(string xmldocasstring, string uri = ): returns the PDF file as a MemoryStream, taking the HTML as a string. This method could be used in a custom.net helper library. The optional uri parameter specifies a file location to write the PDF to; if it is used, null is returned and the PDF file is written to the specified location. If the document passed for conversion contains more than one transaction (which would potentially result in multiple PDFs being created), a warning is issued and only one PDF is created. 10. MemoryStream SingleEdiXmlToPdf(XmlReader reader, string uri = ): see #9; takes an XmlReader instead of a string. 11. MemoryStream MultiEdiXmlToPdf(string xmldocasstring, string uri = ): returns the PDF files generated in a ZIP File as a MemoryStream. This method could be used in a custom.net helper library. The optional uri parameter specifies a file location to write the PDF to; if it is used, null is returned and the individual PDFs are written to the file location. This method is used by other helper methods in the library (such as SavePdfToFile and AssignPdf). 12. MemoryStream MultiEdiXmlToPdf(XmlReader reader, string uri = ): see #11; takes an XmlReader instead of a string. EXAMPLES The following sample code would convert a System.Xml.XmlDocument EDI message (Message_1) to a System.Xml.XmlDocument PDF message in a MessageAssignment shape; it also illustrates how to set a property on the new message: // assigns PDF to new message for use in PassThruTransmit. Message_2 = new System.Xml.XmlDocument(); Tallan.TConnect.EDIConverter.Converter.AssignPdf(Message_1.OuterXml, Message_2); Message_2(FILE.ReceivedFileName) = Message_1(FILE.ReceivedFileName); The following sample code would convert a strongly typed EDI message (Message_1) to a System.Xml.XmlDocument PDF message in a MessageAssignment shape. As above, properties of the resulting message can be set if desired. Message_2 = new System.Xml.XmlDocument(); 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 15 of 16
Tallan.TConnect.EDIViewer.Converter.AssignPdf(Message_1, Message_2); The resultant messages in the above two samples can be routed to a send port using PassThru Transmit and your desired adapter. The following sample code would convert a BizTalk message Message_1 (System.Xml.XmlDocument) to PDF and write the file to the location C:\pdfs using the MessageID as the file name (note: just as for a FILE send port, the logon for the BizTalk host instance must have permission to write to this location). This code would be written in an Expression shape: // Writes PDF file to file location in dll configuration file; dll handles it directly, so some performance benefit Tallan.TConnect.EDIViewer.Converter.SavePdfToFile(Message_1.OuterXml, "C:\\pdfs\\" + Message_1(BTS.MessageID) + ".pdf"); The following sample code would convert a BizTalk message Message_1 (strongly typed) to PDF and write the file to the location C:\pdfs using the MessageID as the file name (note: just as for a FILE send port, the logon for the BizTalk host instance must have permission to write to this location). This code would be written in an Expression shape: // Writes PDF file to file location in dll configuration file; dll handles it directly, so some performance benefit Tallan.TConnect.EDIViewer.Converter.SavePdfToFile(Message_1, "C:\\pdfs\\" + Message_1(BTS.MessageID) + ".pdf"); The following sample code would convert a string containing the XML from a BizTalk message (xmldoc) to a PDF and return a MemoryStream for use in a helper library, which could then do further processing on the MemoryStream: // Convert BizTalk XML message to Zipped PDF Using (MemoryStream memstream = Tallan.TConnect.EDIViewer.Converter.MultiEdiXmlToPdf(xmlDoc)) { } 2014 Tallan Confidential Information: Reprduction or disclosure prohibited. Page 16 of 16