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:

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  

Note:  This Connector is available from the TIBCO Scribe® Online Marketplace. See Marketplace TIBCO Scribe® Certified Connectors for more information.

Special Operations

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

Note: Network locations are not supported for XSD and XML file locations, or for Move File To location options.

  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 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:

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

Note: Formats conform to XML’s restrictions on these data types. Due to these restrictions, Milliseconds are not supported in target XML files.

Special Characters

Schemas

XML Connector as IS/MS Source

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

Source XML File

Query

Data Type Information

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

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.

Target Size

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.

Note: Connection property names are case-sensitive.

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.