Bifrost:XML Data Import

From DigitalVision
Revision as of 14:43, 15 July 2014 by Alastair (talk | contribs) (1 revision: Bifrost Manual pages)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Darrow-up.png     Previous Next

XML Data Import

Data can be imported into a Bifrost project from an XML file, this is the easiest method to exchange data between other data sources such as external database or OCR program.

XML Basics

XML (eXtensible Markup Language) files have a customisable data structure based on HTML and follow the same basic rules. File can be viewed in any text editor (such as Notepad). When editing, it is better to use a more featured editor such as notepad++

The XML file will open with an XML Declaration describing the XML version and encoding used:

<?xml version="1.0" encoding="ISO-8859-1" ?>

Data can then be stored and organised within the file.

An Element (in this case called ‘text’) can be anything you like, the element is everything from the start tag, content and closing tag, in the example below 'This is my data' is the content and the start <text> and end </text> tags give the context of the data.

<text>This is my data</text>

A series of these fields we will call a flat data structure e.g.

<text>This is my data</text>
<text2>This is some more data</text2>

Even in a flat data structure the XML file must be nested inside a root element (called a document entity) e.g.

<root>
<text>This is my data</text>
<text2>This is some more data</text2>
</root>

Elements can be nested within other elements; we will call this a hierarchical data structure, this is analogous to storing files in a folder structure and is useful for organising data e.g.

<text>This is my data
<text2>This is some more data</text2>
</text>

Elements can also contain multiple Attributes e.g.

<text text1=”This is my data” text2=”This is some more data” />

Attribute values must always be quoted

The full specification for the XML format can be found here: http://www.w3.org/

XML Mapping

Mapping data from XML Elements to Bifrost project fields is fully customisable using a mapping file:

C:\BifrostQC\<Program version>\root\Users\AllUsers\BifrostXMLImportMappings.prefs

Multiple mappings can be specified in the same file so that data can be imported from multiple sources.

Bifrost mapping sets use nested preferences, using Braces as a container.

Preference set 1
{  
	preferenceOneName “preferenceOneValue”	
}

If multiple preferences are stored within, Brackets are used as a container (otherwise only the first value will be loaded) e.g.

PreferenceGroupOne
[  
	preference “preference value one”
	preference “preference value two”
]

Here we can look at the mapping set used for importing Bifrost XML files, please open this file for reference:

C:\BifrostQC\2014_1\root\Users\AllUsers\BifrostXMLImportMappings.prefs
XMLImport 			
[				(Container if multiple mapping sets are specified, optional)
	mappingSet 		(Denotes the start of the mapping set, mandatory)
	{		
		name "Bifrost Project"	(name of the mapping set displayed in the GUI, mandatory)

The mapping of XML elements and attributes to project fields can now be specified

roll				(specifies project level data)
{				(container for all project level metadata)
	idEntity "<ImageSystemsXML><RollDescription rollid=>"

This mapping tells the software to derive the project name "Example" from the attribute "rollid" in the following XML structure:

<ImageSystemsXML>
	<RollDescription rollid=”Example” />
</ImageSystemsXML>

Alternatively, the project name can be obtained from the body text of an XML element rather than an attribute. This mapping:

roll				(specifies project level data)
{				(container for all project level metadata)
	idEntity "<ImageSystemsXML><RollDescription><Name>"

would derive the project name "Example" from the following XML structure:

<ImageSystemsXML>
	<RollDescription>
		<Name>Example</Name>
	</RollDescription>
</ImageSystemsXML>


To import data at a clip level:

mappingSet
{
	name "Bifrost Project"
	
	roll
	{
		idEntity "<ImageSystemsXML><RollDescription rollid=>" (Mandatory)
	}	
		
	clip
	{
		nameEntity "<ImageSystemsXML><RollDescription><cuts><Cut name=>" (Mandatory)
	}
}

Will create a Project "Example" with a clip "Clip1":

<ImageSystemsXML> 
	<RollDescription rollid=”Example”>
		<cuts>
			<Cut name="Clip1" />
		</cuts>		
	</RollDescription>
</ImageSystemsXML>
Mapping Different Data Types

XML data can be mapped into the default and custom project and clip fields specified earlier. It is also possible to specify new fields in the XML mapping.


Keywords
mappingSet
{
	name "Bifrost Project"
		
	roll
	{
		idEntity "<ImageSystemsXML><RollDescription rollid=>" (Mandatory)
		keywordEntity "<mapping><project><keywords>"
	}	
		
	clip
	{
		nameEntity "<ImageSystemsXML><RollDescription><cuts><Cut name=>" (Mandatory)
		keywordEntity "<mapping><for><clip><keywords>"
	}
}


Predefined Fields
mappingSet
{
	name "Bifrost Project"
		
	roll
	{
		idEntity "<ImageSystemsXML><RollDescription rollid=>" (Mandatory)
	}	
		
	clip
	{
		nameEntity "<ImageSystemsXML><RollDescription><cuts><Cut name=>" (Mandatory)
		fields
		{
			fieldID (this must match the name specified in default/user.prefs
			{
				entity "<mapping><for><field>"
			}
		}
	}
}
Date Fields

All date fields must specify the date format, for example:

productionDate
{
	entity "<ImageSystemsXML><RollDescription><cuts><Cut production_date=>"
	definition
	{
		name "Date"
		type "date"
		value ""
	}
					
	dateFormat "dd/mm/yyyy"
}

Only numeric dates are supported.

  • A date must contain exactly 1 day field, one month field and one year field.
  • Separators are permitted but not required between fields.
  • d = Day, 1 or 2 characters. Only valid with separators before and after (otherwise ambiguous).
  • dd = Day, always 2 characters.
  • m = Month, 1 or 2 characters. Only valid with separators before and after (otherwise ambiguous).
  • mm = Month, always 2 characters.
  • y = Year, 2 or 4 characters. Only valid with separators before and after (otherwise ambiguous). Optionally followed by + and a base year (1 to 4 digits) for 2-digit years. Otherwise 2000 is assumed as base.
  • yy = Year, always 2 characters. Optionally followed by + and a base year(1 to 4 digits) for 2-digit years. Otherwise 2000 is assumed as base. For example: yy+1915 the year 14 will be interpreted as 2014, 15 will be interpreted as 1915.
  • yyyy = Year, always 4 characters.
  • / = Separator. Matches 1 or more whitespace and/or punctuation characters (in ASCII range). Goes between fields but not at end of string.


Boolean Fields

Boolean fields allow you to translate various inputs to true or false for example:

pCustom1
{
	entity "<Archive><Project><P_Custom1>"
	definition
	{
		name "Project custom field 1"
		type "bool"
		value false
	}
	translation
	{
		translateFalse "false" "f" "no" "n" "off" "0" (Translate any of these to false)
		translateTrue "true" "t" "yes" "y" "on" "1" (Translate any of these to true)
                caseSensitive true/false (default false)
	}
}


Enumerated List Fields

Enumerated lists also allow for translation and the setting of rules when the input data doesn't match the predefined list:

channel
{
	entity "<Archive><Project><Clip Channel=>"
	definition
	{
		type "enum"
		enumerators "Channel 1" "Channel 2" "Channel 3"
	}	
	translation
	[ (requires brackets rather than braces)
		translate "Channel 1" "1" "One" (Translate "1" or "One" in the XML to "Channel 1")
		translate "Channel 2" "2" "Two"
		translate "Channel 3" "3" "Three"
	        caseSensitive false (true/false, default false)
                unrecognised "fail"
	]
}

unrecognised "fail" sets the behaviour when an XML value doesn't match the list or the translations

  • "copy" -> copy the XML text verbatim to Bifrost enum field.
  • "fail" -> fail to import this Bifrost enum field.
  • "set" "value_to_set" -> set the Bifrost enum field to the value specified by "value_to_set".*
  • If this preference is absent the software will apply the copy behaviour but warn the user that this happened.

Darrow-up.png     Previous Next