TIBCO Scribe® Online Connector For XML

Use the TIBCO Scribe® Online Connector for XML to read data from or write data to an XML file on the local file system. This Connector uses XML Schema Definition (XSD) files to support simple properties, complex properties, and Collections.

Possible use cases for the Connector For XML include:

• Integrating data from a legacy system that does not have an API and does not allow access to its databases.
• One time migrations from a legacy system into another database or application.
• Reading XML documents from an outside source and sending them into a target application.

Connector Specifications

This Connector supports version 1.0 of the XSD.

	Supported
Agent Types
On Premise	X
Cloud
Replication Services
Source
Target
Integration Services
Source	X
Target	X
Migration Services
Source	X
Target	X
Maps
Integration	X
Request-Reply	X
Message

Special Operations

• CreateWith — Container Block used with hierarchical data. This Block collects all of the data for a single record before writing the entire record to the target. For example, if the record is a SalesOrder containing five SalesOrderItems, the CreateWith Block, along with an Add Block, retrieves both the SalesOrder and the associated SalesOrderItems and writes the entire record at once to the target. When writing to an XML file, each record is stored in a separate XML file. See CreateWith Block. To append all records to the same XML file, use the BuildWith Block.
• BuildWith — Container Block used with hierarchical data. Typically this Block is used when you need to write data in a hierarchical format with multiple records per file. For example, if you have a list of Books in SQL and you want create a single XML file with BookList as the parent and the individual Books as children, the BuildWith Block adds all Books to a single XML file. The CreateWith Block creates a separate XML file for each Book. This Block is similar to the CreateWith Block.

  To use the BuildWith Block, your XSD schema file must be configured such that the top level element is a sequence that can contain a list of items.

• Add — Used for hierarchical data to add child records to the parent selected in the CreateWith or BuildWith Block. See Add Block.

Selecting An Agent Type For XML

Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.

Connecting To XML

1. Select More > Connections from the menu.
2. From the Connections page select Add to open the Add a New Connection dialog.
3. Select the Connector from the drop-down list in the Connection Type field, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • XSD Full Path and File Name — The complete path and file name of the XML schema definition file (XSD) on the Agent Server to use with the XML file being read or written. This directory does not need to be the same directory where the XML files are stored. Example: C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\DataExchange\MyXMLFiles\purchasOrder.xsd
   • XML Folder Path — The complete path to the directory on the Agent server where the XML files are stored, such as C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\DataExchange\MyXMLFiles

   Note: When setting either the XSD Full Path or the XML Folder Path, note that this is the path on the server where the Agent is installed, NOT the computer used to run the TIBCO Scribe® Online user interface.

   The XSD Full Path and File Name field has a maximum of 255 characters. Wildcards can be used if the path and file name exceed 255 characters. Example: C:\Program Files (x86)\Scribe*\*16\purchaseOrder.xsd instead of C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent 16\purchaseOrder.xsd

4. In the Read section, enter the following information:
   • XML File Name — Name of the XML file to read from the directory specified in the XML Folder Path field.
   • Post Processing Rule — Determines what happens to the associated XML file after the data it contains has been processed by a Map. Options include:
     • Do Nothing — Leaves the file in the source directory.
     • Move File To: — Moves the source file to the directory specified in the Location field and renames the file. The full path and new file name or rename parameters are required. To make the file name unique, specify one or more of the following rename parameters:
       • [File] — Inserts the current file name.
       • [Date] — Inserts a datetime stamp.
       • [Status] — Inserts either Success or Failure.
         • Success — Map ran successfully, but there may be record errors.
         • Failure — Map failed to run. Typically triggered by a more significant error such as a Fatal Error.
       Note: 

       • If only folder name is specified in the Location field, the source file is not moved.
       • If the file name specified in the Location field matches a file that already exists in the directory specified in the Location field, the file is not moved.
     • Delete File — Deletes the file.

     Note: When an error occurs during processing, the file is not deleted or moved, and file Failure status is added to the file name.

5. In the Write section, enter the following information:
   • XML File Name — Name of the XML to write, including the .xml extension. If the extension is not included, a text file (.txt) is created.
   • Target Processing Rule — Determines what happens if a file by the same name already exists. Options include:
     • Overwrite Existing File — Deletes the existing file and creates a new file with the same name.
     • Create New File With Timestamp — Creates a file that includes a date/timestamp in the file name. This prevents existing files from being overwritten since each filename is made unique by the addition of the timestamp. Date/timestamps on XML target files are local time based on the installation location of the Agent.

     Note: Each processed source record can be written to a separate target XML file or appended to the same target XML file depending on whether you use a CreateWith or a BuildWith Block. CreateWith creates a separate file for each record and BuildWith creates a single file containing all records.

6. Select Test to ensure that the XSD file exists, the Folder Path exists, and either the Read or Write XML file is specified. Be sure to test the Connection against all Agents that use this Connection. See Testing Connections.
7. Select OK/Save to save the Connection.

Metadata Notes

Consider the following for XML data fields and entity types.

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

DateTime

When mapping dates and times in the Fields tab from an XML source file:

• Dates show as Strings
• Times show as Strings
• DateTimes show as DateTimes

In the target XML files dates and times are written as follows:

• Dates are always in the format: YYYY-MM-DD
• Times are always in the format: hh:mm:ss
• DateTimes are always in the format: YYYY-MM-DDThh:mm:ss

Special Characters

• This Connector supports all allowable XML characters in fields. The following characters are not supported:
  • & (ampsersand)
  • > (greater than)
  • < (less than)

Schemas

• You can only use one schema (XSD) file. This file must be on the same server as the source and/or target XML file, but can be in a different folder.
• Schema files are validated when the Connection is tested or saved.
• If your schema uses namespaces and you make changes to your XSD schema file, you must create a new XML Connection that uses the updated XSD. Update any Maps that use the old Connection to use the new Connection.

XML Connector as IS/MS Source

Consider the following when using the XML Connector as an IS source.

Source XML File

• If the XML Connection Post Processing Rule for source XML files is set to either MoveFileTo or DeleteFile, the source XML file is either moved to a different directory or deleted after being processed by a Solution. Subsequent executions of any Solution using that Connection run without generating any errors even though there is no source XML file in the location configured on the Connection dialog. Execution History indicates that the Solution ran successfully and 0 records were processed.
• If your file contains malformed XML, errors are generated when attempting to use the Preview tab in the Query Block and a fatal error is generated when the Map runs.

  For example, if your XML file contains:

  <child name=>

  instead of

  <child name="">

  The Execution History error would contain a message similar to the following:

  '>' is an unexpected token. The expected token is '"' or '''. Line 158, position 26.

Query

• The root element and top level elements where the maxOccurs attribute is greater than one can be selected as an entity in the Query Block. Other related elements can be selected on the Include tab of the Query Block to return related data.

  For example, if the Accounts entity contains multiple Contacts, and each Contact entity contains multiple Addresses, you can select Contacts and Addresses from the Include tab on the Query Block.

• Filtering for new and updated records on the Query Block Net Change tab is not supported nor is filtering on the Filter tab.
• The Lookup Block is not supported.
• On the Include tab, Inner joins or Return only records with this relationship, are not supported.
  • If selected on the Query Block Include tab, a Fatal Error is generated when the Map is run.
  • If selected on the Fetch Block Include tab, a record error is generated indicating that this selecting is not supported.
• The Fetch Block does not support filtering for this Connector.

Data Type Information

Defined values are displayed on the Query Block Preview tab in either the Type (Size) column or the Description section:

• Type (Size) column
  • Length
  • maxLength
• Description section
  • Annotations/Documentation
  • enumeration
  • maxExclusive
  • maxInclusive
  • minExclusive
  • minInclusive
  • minLength
  • pattern

XML Data Types

Most data types in TIBCO Scribe® Online correspond to those in XML. For example, the XML type System.Decimal is converted to Decimal in TIBCO Scribe® Online. Data type exceptions include the following:

XML Data Type	TIBCO Scribe® Online Type	Notes
anyURI	String
anySImpleType	String
date	String	XML expects this field to be passed as a date format even though it is a string, such as "11/22/1967".
dateTime	DateTime	Must be surrounded by quotes to pass validation, such as "12/18/1945" or "1945-12-18".
duration	String
gDay	String
gMonth	String
gMonthDay	String
gYear	String
gyearMonth	String
int	Integer
Integer	Decimal
NMTOKENS	Object
QName	String
time	String	XML expects this field to be passed as a time format even though it is a string, such as 11:35:45.123". XML does not support milliseconds, so they are removed.
SByte	Int16
simpleTypeList	String
simpleTypeUnion	Object

XML Connector As IS/MS Target

Consider the following when using the XML Connector as an IS or MS target.

• Batch Processing is not supported for this Connector.
• Creates XML files that support W3.org XML specifications for Namespaces and schemas.
• The associated XSD file provides the schema or layout for the target data and controls how records are written to the target XML file.

Target Size

• No size restrictions are imposed on files that are created.
• One output file is created for each record when using CreateWith.
• All records are added to a single output file when using BuildWith.

TIBCO Scribe® Online API Considerations

To create connections with the TIBCO Scribe® Online API, the XML Connector requires the following information:

Connector Name	XML
Connector ID	81AE9106-80CB-4078-9FFD-1B89B9DD8A43

TIBCO Scribe® Online Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Name	Data Type	Required	Secured	Usage
XsdFile	string	Yes	No	Full path including file name of the XSD file.
FolderPath	string	Yes	No	Path for the directory containing the source and target XML files.
ReadXmlFile	string	No	No	Either ReadXmlFile or Write XmlFile is required. Name of the source XML file. Full path is optional if FolderPath is used.
WriteXmlFile	string	No	No	Either ReadXmlFile or Write XmlFile is required. Name of the target XML file. Full path is optional if FolderPath is used.
ReadXmlFileProcessing	string	No	No	Valid values: •   None •   Move •   Delete Default value is None.
MoveXmlFilePattern	string	No	No	Required if Move is selected in ReadXmlFileProcessing. Full path using [File], [Date], and [Status] keywords
OverwriteFile	boolean	No	No	Used with WriteXmlFile to determine treatment of target files. Valid values: •   true - Overwrites existing files. •   false — Creates a new file with a date timestamp.
WriteDocumentType	string	No	No	Valid values: SingleEntity
FileserviceType	string	No	No	Valid values: WindowsFileSystem

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.