The standard library of SPARQLMotion modules. This library may be split into multiple physical files in the future, but the URIs of the module types and properties will be stable.
2.2.3
Serialization
The various serialization formats of RDF/OWL files, including RDF/XML and N3.
Database type
The class of database configurations used by Jena SDB (and possibly other databases).
The export modes supported by Oracle RDF.
Oracle export mode
ExportBatch
ExportBulk
ExportIncremental
OWL_MEM
OWL_MEM_MICRO_RULE_INF
OWL_MEM_MINI_RULE_INF
OWL_MEM_RDFS_INF
OWL_MEM_RULE_INF
OWL_MEM_TRANS_INF
OWL_DL_MEM
OWL_DL_MEM_RDFS_INF
OWL_DL_MEM_RULE_INF
OWL_DL_MEM_TRANS_INF
RDFS_MEM_RDFS_INF
RDFS_MEM_TRANS_INF
Jena inferencing mode
The inferencing types supported by Jena.
sql
className
instancePattern
askQuery
An XPath expression.
xpath
separator
bind variables
useUnderscore
class
predicate
view
xml
text
smtpServer
The name of a variable that shall contain the iteration index in a loop, starting at zero.
iteration variable
import to input graph
single pass
datatype
graph name
filterGraph
Links a filter module with a predecessor module to mark the predecessor module graph to be used for filtering in the filter module.
value
hidden
url
addedPrefix
rowQuery
selectInstanceClass
Prompts the user to select an instance by class, and binds the selected resource into the specified output variable. If not selectInstanceClass is specified, then the selection would start at the root class.
true
the title of the selection window
true
the label of the button to continue
Select instance
The name of the variable that shall contain the selected resource.
Modules that import information from some data source. Examples include modules to load files, to get XML from web sources and to take user input.
Import
true
0
true
Import from Various
The (optional) class that shall be used as root of a class/instance selection box.
true
schemaNamespace
selected resource
The suggested default property to use in conjunction with sml:SelectedResourceArgument.
calendarProperty
Creates a calendar view showing resources from one or more SPARQL select queries. Currently only supported within TBC.
The property that hold the relevant xsd:date and xsd:dateTime values.
Create calendar
true
Modules that create some output, such as files or UI components.
Export
2
true
Export to Various
1
A SPARQL Select query that returns the subjects that shall be displayed in the calendar. In a typical use case, this query would bind a single result variable that iterates over all "events", where each event has an xsd:date/time value attached to it using sml:calendarProperty.
The properties that shall be shown in the calendar.
old graph
result
database type
new graph
columnQuery
propertyPrefix
replace
Specifies whether a module shall overwrite all triples from its predecessors. If set to true (default is false), then the triples from the predecessors shall not be passed through.
title
variable
template
constructQuery
java class
targetFilePath
inferencingMode
A SPARQL UPDATE query (can be used to insert or delete triples from a graph).
update query
password
serialization
emailAccount
snippet
useVerbatim
input variable
path
Can be used to represent path expressions such as /INBOX/TBC-MailingList
data path
encoding
userName
loadBodies
modelName
cellQuery
deletedPrefix
sourceFilePath
The path to a file relative in the execution context (workspace). Values can be relative to the currently executing script (e.g., subFolder/file.txt) or absolute to the workspace root (starting with /).
needs tidy
on commit
cached
uri
button label
(Reserved for future use.)
mimeType
ignore imports
select query
xmlType
XHTML
The base URI of an RDF model.
baseURI
ruleBaseName
Import from Remote
true
Opens an HTML document from a URI, using Tidy to convert it to XHTML (XML). The url must point to the URL of the file. The URL may contain variables from the input modules. The resulting XML will be assigned to the specified output variable.
The name of the variable that will contain the XHTML as an XML document. Default: xml.
xml
Import XHTML
The URL of the HTML page. May contain variables such as {?varName}.
Represents the exit point of a function that returns XML. The function can be referenced from the outside (e.g., as a web service) by its URI or local name.
Return XML
true
Export to Remote
The XML document that shall be returned.
true
The (optional) mime type of the result stream.
text/xml
Represents the exit point of a function that returns text (mimetype: text). The function can be referenced from the outside (e.g., as a web service) by its URI or local name. When called from TBE, the resulting text will be displayed to the user in a pop-up dialog.
Return text
The (optional) mime type of the result stream.
text
true
true
The text that shall be returned.
Gets RDF data from a given URL. The URL may just point to an RDF/XML file on the web, or call a web service with REST-style parameters to receive RDF/XML back. No other format beside RDF/XML is supported by this module - use sml:ImportRDFFromWorkspace instead.
The URL of the RDF source. May contain variable bindings such as {?varName}.
Import RDF from URL
Runs a SPARQL Select query and returns its result in the standard SPARQL output format.
The SELECT query to execute.
1
1
Return SPARQL results
the serialization format such as XML or JSON
true
Bind by select
true
1
Processing
true
Modules that process data, e.g. to transform, filter and map it.
Control Flow
Runs a SPARQL select query and binds all result variables of the first matching result set. The input RDF is simply passed through to the next module. For example, if you run SELECT ?name ?age WHERE { my:Person my:name ?name ; my:age ?age } then the variables name and age will be bound as output variables.
A SPARQL Select query that is executed over the input triples. The result variables of the first result row will be bound in the succeeding modules.
1
1
The name of the output variable that will contain the result.
text
true
The serialization format.
Serialize SPARQLResults
true
Text Processing
Executes a SPARQL SELECT query and serializes its result to either XML or JSON format.
1
1
The SELECT query to execute.
Oracle
Merge
This module type can be used to merge the variables and RDF triples from multiple input modules. The same is done by any other SPARQLMotion script that has multiple input modules. So while the sml:Merge module basically does not do anything at all, it can be useful to create a clean structure in your script, particularly if you have a case when you want to merge multiple graphs and then have multiple outgoing sm:next links from the merged graph.
Gets XML from a given URL and binds the resulting XML document to a specified output variable. Note that this could either be used to load static XML files from the web, or to call web services that return XML.
Import XML from URL
The URL to the XML file. May contain variables such as {?varName}.
xml
The output variable that will hold the loaded XML. Default: xml.
Takes a comma-separated list of URIs as input and creates an rdf:List from it which is then visible to all modules downstream. The rdf:List will be a blank node (or rdf:nil) and the provided output variable will point to it. Note that the RDF output of this module consists of the rdf:List triples only, i.e. the input triples are not passed through.
Among others, this module can be used by web services that take lists as input.
Convert text to RDFList
list
the name of the output variable that will contain the rdf:List
the comma-separated list of URIs
Convert text to RDF
Converts a text in one of the RDF serializations into an RDF graph. In a typical scenario, the text would be passed into the script as external (web service) input. The result of this module are the input RDF triples plus the parsed triples.
N3
The (optional) serialization format, e.g. N3, XML, Turtle or NTriple. Default: N3.
true
The text to parse.
Prompts the user to select one resource out of a list of resources delivered from a SPARQL query. The selected resource will be bound to the specified variable. Any RDF triples that come in as input are forwarded as output.
This module is currently not supported by TopBraid Ensemble.
A SPARQL Select query that delivers the resources that shall be selectable in the UI box.
1
1
true
the title of the selection window
Select resource
true
the label of the button to continue
The name of the variable that shall hold the selected resource.
Bind literal variable
The name of the output variable.
The target datatype, e.g. xsd:string or xsd:int. Default: xsd:string.
Binds the output variable with a constant of a given datatype, or with a value derived from one or more other input variable values. The template could be as simple as {?varName} to insert the variable's value or more complex such as {?firstName} {?lastName}. This module can also be used to convert the datatype, e.g. to convert a xsd:string into a xsd:float.
the template string
Clone variable
The name of the input variable that shall be cloned.
The name of the output variable that will be created.
Clones a given variable value and assigns it to a new output variable. The input variable will keep its value.
This module can be useful to "rename" an existing variable so that it has a matching name that is expected by modules downstream in the script. For example, if you have a variable ?xmlFile but a next module expects an input argument ?xml (via an argument sml:xml), then you can use sml:CloneVariable to bind ?xml with the value of ?xmlFile. Note that in many (most?) cases, you can achieve the same by using inline SPARQL expressions: in TBC use "Add SPARQL expression" from the context menu of the property name and enter an expression such as ?xmlFile at the sml:xml property.
The database type, e.g. Oracle.
true
Indicates whether all existing content of the SDB shall be overwritten.
the named graph URI
true
true
The user name to log in with.
The URL of the database.
true
The password to log in with.
The base URI of the target SDB database. This will serve as a unique identifier of the triple store in TopBraid, and is typically also represented by an owl:Ontology.
The (optional) path to a .sdb file that can later be opened from within TopBraid.
true
Export to SDB
Writes the input triples to a specified Jena SDB database.
Note: This is a low-level system module. The preferred way of writing to databases is using sml:PerformUpdate.
Runs a SPARQL Ask query and, depending on the resulting boolean, either continues with the sm:if or the sm:else branch. Both branches can be sub-scripts, and the sm:if and sm:else should point to the entry points of those sub-scripts. Those entry modules will be passed the same RDF triples and variable bindings as passed to theBranchByAsk module itself. The result of the execution will be the target module (last module in the sub-script) of the selected branch. All variable bindings of the result module will also be passed on as output to the next module(s). Both branches must have exactly one target module. If a branch is empty then the module's input will be passed on unchanged.
The start of the child script that shall be executed if the ask query evaluates to true.
0
1
Branch by ask
1
The start of the child script that shall be executed if the ask query evaluates to false.
0
The SPARQL Ask query that delivers true (sm:if) or false (sm:else) to determine the branching condition.
1
1
Imports the RDF Schema and OWL system triples, including the definitions of owl:Class, rdf:type, rdfs:label, rdfs:seeAlso etc. An example use case where this is needed is if you want to query for the rdfs:label of any property including system properties. Another use case is if you want to walk the class hierarchy (using rdfs:subClassOf) including metaclasses and other system classes.
Import system triples
Check constraints
true
RDF Processing
Runs all SPIN constraints defined in the current input graph. The output of this module will be a new RDF graph that only contains the spin:ConstraintViolation instances. If the SELECT query is specified, then only the selected resources will be checked, not the whole model.
An (optional) SPARQL SELECT query that delivers the resources that shall be checked.
0
1
true
Indicates whether this is a "hidden" argument. Hidden arguments will not be presented to the user in input dialogs but instead always have their defaultValue.
A system argument representing the "selected" resource. This can be used to implement services that operate on the currently selected resource in TopBraid Composer or Ensemble. The value of this argument will be set automatically by the engine in TBC. In TBE the selected resource's URI needs to be passed in.
Note: this replaces sml:BindWithSelectedResource from older TBC versions.
Selected Resource {?predicate}
Selected resource argument
The path to the TBD data files. This is usually the .tdb connector file name plus .data.
Import TDB
Modules that import data from a data source on the user's local machine.
true
Import from Local
Opens a Jena TDB database stored in the workspace at a given path.
Note: This is a low-level system module. The preferred way of operating on existing TDBs is using sml:ImportRDFFromWorkspace.
Applies one of the Jena inference engines on the input triples.
Apply Jena inferencing
Specifies the Jena inferencing mode that shall be applied. The permitted values must be instances of sml:JenaInferencingSpec. Default spec is RDFS_MEM_TRANS_INF.
sml:RDFS_MEM_TRANS_INF
Can be used to implement services that shall be executed as a side effect of a change to an RDF model. In TopBraid, any script containing an instance of this class will be executed as part of each change. The output of this module is using the http://topbraid.org/change ontology, with triples describing the changes that have happened.
Can be used (in TopBraid Live only) to specify that a script shall be executed after commits, and not after edits. In TBC this is ignored, and script will always be executed after edits.
true
Track changes
Runs the OWLIM inferencer over the input triples, adding the inferred triples.
Note that this SPARQLMotion module does not (yet) support the various settings of OWLIM that are accessible through TBC. Let us know if you need any of them!
Specifies whether the resulting infererred triples shall replace the input. If false, the union of inferred triples and old triples are returned.
Apply OWLIM
Filter by filter graph
Filters input graphs with filter graphs. This module is linked to filter graph modules by sml:filterGraph property.
The module that contains the triples that shall be filtered out. Must be one of the predecessors of this module, to make sure that it has been executed before.
Indicates whether the bodies of the email should also be downloaded. Note that the value of true will be significantly slower than the (default value) false.
true
The address to load the emails from. The address must have valid values for email:userName, email:protocol, email:password, email:server.
The base URI of the RDF objects created from the emails.
true
An (optional) path to those folders the headers of which shall be loaded. For example /INBOX/TBC-MailingList will load the emails from the TBC-MailingList folder inside of the INBOX folder.
Import emails
Imports email messages from an account. This feature is based on the TopBraid email ontology (http://topbraid.org/email). The property sml:emailAccount must point to one email:Address instance. The system will connect to the account and import its emails into OWL instances of the email ontology.
The body of the iteration loop.
1
1
Iterate over select
A SPARQL Select query that determines the variable bindings for the body in each iteration.
1
1
true
The name of a variable which will contain the iteration index in each loop, starting with 0.
Repeats a given sub-script for each matching result set for the SPARQL Select query in the module's selectQuery property.
The start of the sub-script is specified by the body property. There can only be one body property that invokes a single sub-script. The sub-script must have one target module -- that is, the sub-script cannot have multiple termination points.
The input RDF for each iteration is the same as the input of the iteration module itself. The result variables of the Select query will be bound inside the body in each iteration of the sub-script. Also, if the sml:IterateOverSelect module itself receives input variable bindings, and the value of these variables are changed inside the body sub-script (e.g. using sml:AppendText or sml:BindLiteralVariable), then the end value of each iteration will be used in the sub-script itself, and thus also passed into the next iteration's body. This allows scripts to incrementally modify variables. The property sml:iterationVariable can be used to name a variable that will keep an iteration count.
The result of this module are the accumulated triples from the end node of the body sub-script. No internal variable bindings of the body will be used outside of the body, unless they have had values before (see above).
In many cases, a better alternative to creating "loops" is to use SPARQL directly, and embed some of the control logic into the WHERE clause, possibly through a CONSTRUCT or UPDATE query.
Perform update
The SPARQL UPDATE query to perform. The supported syntax is explained here: http://jena.hpl.hp.com/~afs/SPARQL-Update.html
1
1
Performs a SPARQL UPDATE call to insert and/or delete triples. This module differs from sml:ApplyConstruct (and other module types) by making persistent changes when the script runs. Therefore this module should be used carefully.
The default graph of the WHERE clause is the input graph of the module, i.e. the result of its predecessors. However, these cannot be modified using INSERT or DELETE. Instead, a named graph needs to be provided there, e.g. using MODIFY GRAPH, INSERT INTO or DELETE FROM. In order to manipulate the currently open model in TopBraid, there is a special named graph with the URI <urn:x-tb:session> (formerly called <http://tb-session>). Another special graph is <urn:x-tb:sessionbase> that is mapped to the unbuffered version of the base graph of the current session. In the context of an editing application such as Ensemble, this means that any uncommitted changes are bypassed and instead writes are directly done against the database.
SPARQL does not support the use of variables as target graphs, e.g. INSERT INTO ?var is not allowed. In some cases it is necessary to dynamically determine the target graph though. In those cases, the special named graphs <urn:x-var:VARNAME> can be used. VARNAME must be a bound variable pointing to a URI. These URIs must be specific files in the workspace, and it is not valid to redirect to other special URIs such as <urn:x-tb:session>.
If this module is used within a TBE script, then the updates to urn:x-tb:session will be applied like other changes by the user, i.e. they are added to the change history without committing them. Changes are committed when the user selects "Save Data". All other named graphs will be committed immediately to the underlying data store.
true
The user name if required to log into the repository.
Export to Sesame remote repository
true
true clears the repository before writing into it.
The URL of the Sesame server.
the graph name URI
true
The id of the model on the server, if necessary.
true
Writes the input triples into a Sesame remote repository.
Note: This is a low-level system module. The preferred way of writing to databases is using sml:PerformUpdate.
An (optional) path to a connection metadata file that will be created so that tools can connect to the repository later. This path is relative to the workspace root, e.g. "/myProject/myFolder/myFile.s2r". Must be used in conjunction with sml:baseURI.
true
The base URI of the target repository. Must be specified if a connection file (*.s2r) shall be created.
true
true
The password if required to log into the repository.
text
The name of the variable that will hold the resulting spreadsheet string. Default: text.
The separator between each column. Default is the tab character, but a typical alternative is ",".
true
Create spreadsheet
The SPARQL Select query that delivers the rows of the spreadsheet. The columns will be the result variables of the query.
1
1
Creates a spreadsheet text from all bindings of a SPARQL SELECT query. The resulting text will be bound to a variable and can then be saved to a file or further processed.
The path to the file that shall be created. The path can be relative to the current script's folder (e.g., myFolder/test.txt) or absolute to the workspace root /myProject/myFolder/test.txt.
Saves text to a file. The text must be the value of the specified input variable.
The text that shall be written into the file.
Export to text file
Export to Local
true
Specifies whether this will overwrite a file with the same name (true) or whether it will append to an existing file (false).
true
Runs a JSP (with embedded SPARQL) template over the input triples and binds the resulting text as a new string variable. For more see Help > Import and Export > Generating XML/HTML documents with Semantic Java Server Pages.
Note that UISPIN is often a good alternative to JSPs.
True to only create a UISPIN snippet, e.g. without head/body.
true
The name of the output variable that will contain the resulting document (as a string).
doc
The UISPIN snippet to evaluate.
Create UISPIN document
Evaluates a given UISPIN document (sml:view) and assigns the resulting XML document to a given string variable (sm:outputVariable). The new variable can then be saved to a file or processed otherwise. All incoming variables of this SM module will be bound in the UISPIN expression.
Note that in order to insert a UISPIN view for a given resource (using ui:instanceView etc), you can use the snippet <ui:resourceView ui:resource="{= ?varName }" />.
Also note that in order to use HTML or SVG tags in the sml:view, you will need to import the html.rdf or svg.rdf from the UISPIN ontologies into the script.
The name of the variable that will hold the output of the JSP as an xsd:string. Default: text.
text
false
If set to true then all currently visible variables of the SM script will be pre-bound in the SPARQL queries in the JSP. Default is false, and users can access the script variables using a construct such as <sparql:select var="rs" cls="${param.rsc}"> where ?rsc is a variable in the SPARQLMotion script.
true
Create text from JSP
The Semantic JSP template, typically the content of a JSP file that was loaded in a previous step.
PostgreSQL
Uses SPARQL CONSTRUCT queries to enumerate triples that shall be dropped from the input triple stream. The output triples of this module contain all input triples except those enumerated by the construct query. For example, if you want to drop all rdfs:comment triples from the input graph, then use a query such as CONSTRUCT {?s rdfs:comment ?o} WHERE {?s rdfs:comment ?o}.
A SPARQL Construct query delivering the triples that shall be dropped.
1
Filter by construct
The name of the variable to bind.
value
The XML document or node to operate on.
Evaluates an XPath on a given XML node (or document) and binds the first result to a given variable.
true
The datatype of the result variable (xsd:string if left blank).
true
XML Processing
Bind by XPath
The XPath to process.
The path of the file to create. The path can be relative to the current script's folder (e.g., myFolder/test.rdf) or absolute to the workspace root /myProject/myFolder/test.rdf. Can be left blank if the base URI already has a representation in the workspace. In that case, the primary file in the workspace will be overwritten.
true
The base URI under which the resulting file will be registered in the workspace.
Export to RDF file
Creates a new RDF file at the specified path inside the workspace and with the specified base URI. The serialization is derived from the file name according to TopBraid's conventions, e.g. files ending with .ttl will be written in Turtle format.
Note that if an existing file is overwritten (with matching base URI), and the graph of this file has already been loaded, then the system will not reload the new graph. I.e. if the URI specified in sml:baseURI is the same baseURI of a graph currently open in TBC or TBL, the old graph will remain open and the export will only have an effect after closing the other copies. A consequence of this is that you cannot overwrite a file and reload its new content within the same session, e.g. sml:ImportRDFFromWorkspace will still deliver the old graph. In order to modify an existing graph, the recommended approach is to use sml:PerformUpdate.
Iterate while
Repeats a sub-script (specified as body) as long as a SPARQL ASK query returns true. The output of each iteration is the input to the next. The output of the whole module is the result of the last iteration. No variable bindings are passed into or out of the body.
The start of the script that shall be executed as body in each iteration. The body must end with a single target module.
1
1
1
1
An ASK query that is executed prior to each iteration. If the query returns false, the iteration stops and the most recent result graph will be returned.
Converts a SPARQL query (in textual form) to a SPIN RDF syntax resource. The resulting output graph will contain exactly the triples of the SPIN query. These triples can then be used, for example, to analyze the structure of a SPARQL query dynamically. The inverse operation can be achieved using the SPARQL function smf:convertSPINRDFToString.
the SPARQL query in textual form; with or without namespace prefixes
Convert string to SPIN RDF
the URI of the query to create (either xsd:string or resource)
true
Convert datatype
Replaces all triples that have a given property as predicate (specified by sml:predicate) by converting its object literals into a different RDF datatype (specified as sml:datatype).
The predicate of the triples that shall be replaced.
The datatype (e.g. xsd:string) of the new triples. If the datatype is rdfs:Resource and the lexical form of the old value is a valid URI, then the resulting triple will point to a resource with that URI.
Can be used to add or delete namespace prefix declarations from the input RDF stream so that these new prefixes are visible down stream of this module.
Modify prefixes
0
Namespaces to add, in the format "prefix namespace", i.e. the prefix must be followed by a space. Example: "my http://my.com#".
The prefix(es) to delete, e.g. "my".
0
Turtle
An (optional) comment that is only used in teamwork mode, to attach a comment to a Change object. This comment can be collected from the user in earlier steps of a SM script.
true
Commit changes
This module can be used in conjunction with TBE sessions to commit changes from the session's buffers into the underlying data stores. This is comparable to the "Save Data" button in TBE.
Imports a text file into the xsd:string variable sm:outputVariable.
text
The name of the variable that will contain the text of the file as an xsd:string literal. Default: text.
The path to a text file. The path can be relative to the current script's folder (e.g., myFolder/test.txt) or absolute to the workspace root /myProject/myFolder/test.txt.
Import text file
Loads an EMF file from the workspace and makes it possible to process the resulting Java objects further down in the script (e.g., with sml:ConvertJavaObjectsToRDF).
The name of the output variable that will contain the reference to the Java objects.
java
The path to the EMF file.
Import java objects from EMF file
In scripts that are called as web service, this module can be used to iterate over all arguments of the web service. In each iteration, the body will be executed with two variable bindings: the argument name (?argName) and argument value (?argValue), both as xsd:string literals. The result of the module itself will be the union of the results of all body iterations, comparable to sml:IterateOverSelect. In a typical scenario, the body would consist of sml:ApplyConstruct modules that turn the raw arguments into some more meaningful data structure, that is then further processed by the rest of the script.
1
1
The body to execute with the two variable bindings (?argName and ?argValue).
Iterate over arguments
Convert JSON to RDF
root
true
The name of the result variable (defaults to "root") that will contain the root object of the converted JSON code.
The JSON input text, either a JSON object or array.
Takes a JSON object or array (represented as text) and converts it to RDF triples with the same structure. The result graph will only contain the generated triples - the input graph will be ignored and may need to be passed on with a separate sm:next relationship. The graph uses the namespace prefix "json" for http://topbraid.org/json#.
The conversion will start at the JSON root and does a recursive walk through of the JSON objects and arrays. Each JSON object becomes a blank node of type json:Object. Each attribute of the JSON object is mapped into a property from the json namespace, e.g. attribute "firstName" becomes a property json:firstName. No types are generated for those properties (but a simple CONSTRUCT could be used). The values of those properties depend on the JSON attribute value. Arrays are converted to rdf:Lists, JSON objects recursively become new blank nodes. Numbers, booleans and strings become corresponding RDF literals.
Optionally, the module can bind a new variable pointing at the root object of the new JSON data structure in RDF.
The internal Oracle database name.
The URL of the database.
Import Oracle RDF database
Connects to an Oracle 11g RDF database.
Note: This is a low-level system module. The preferred way of operating on existing databases is using sml:ImportRDFFromWorkspace.
Indicates whether the Oracle database shall be wrapped with a local cache for optimized performance.
true
true
The (optional) password to log into the database.
The (optional) user name to log into the database.
The name(s) of rule bases that shall be used for server-side inferencing. The standard inferences are RDFS, RDFS++, OWLSIF and OWLPRIME.
Represents the exit point of a function that returns RDF. The function can be referenced from the outside (e.g., as a web service) by its URI or local name. The RDF triples will be serialized into either RDF/XML or JSON.
RDF/XML-ABBREV
the serialization format
Return RDF
true
The user name if required to log into the repository.
The password if required to log into the repository.
true
true
The id of the model on the server, if necessary.
the named graph URI
true
Import Sesame remote repository
The URL of the Sesame server.
Connects to a remote Sesame 2 repository.
Note: This is a low-level system module. The preferred way of operating on existing databases is using sml:ImportRDFFromWorkspace.
The URL of the RDFa file (typically HTML).
Import RDFa
true
If set to true, the engine will attempt to clean up the HTML so that it becomes well-formed XHTML.
Imports the RDF triples from a given RDFa page with a given URL.
Depending on the file format, other kinds of pre-processing may be needed to tidy up the HTML into proper XHTML. This can be specified with an option. By default, well-formed XHTML is assumed.
Enter literal
the text that will appear at the prompt
true
true
The type of the value to enter (e.g. xsd:int). Default: xsd:string.
Prompts the user to enter a literal. The resulting value will be bound as literal to the variable specified as sm:outputVariable.
The name of the variable that will contain the entered literal.
MySQL
true
If set to true, the output triples will only contain the constructed triples. If no values or false are specified, the output will be the union of the input triples and the constructed triples.
The SPARQL Construct queries that deliver the triples that shall be added.
1
Runs one or more SPARQL Construct queries on the input triples. The output RDF will consist of the constructed triples and (unless sml:replace is true) the input triples.
Apply Construct
Applies the TopSPIN rules inference engine on the input graph. This assumes that the input graph contains one or more SPIN rules (stored using the property specified under sml:predicate, which defaults to spin:rule).
Apply TopSPIN
The predicate to get the rules from. Usually spin:rule, but can be any SPIN property (subPropertyOf spin:query)
true
Specifies whether only a single pass over all rules shall be made. By default (false), TopSPIN will iterate until no further inferences have been made.
true
true
Specifies whether the resulting infererred triples shall replace the input. If false, the union of inferred triples and old triples are returned.
The names of the Java classes in scope of the conversion. All (indirect) instances of those classes will be included in the conversion. The names may end with .* to indicate packages.
The name of the variable that is currently pointing to the Java objects to convert.
java
The name of an output variable that will contain the root object (in RDF).
true
Converts Java objects (e.g. loaded using sml:ImportJavaObjectsFromEMFFile) into RDF classes, properties and instances that have the same structure. The module will start at a root object and traverse all properties of that object (using JavaBeans-like getter methods), converting each instance into RDF blank nodes. The traversal into adjacent objects only continues if the object has one of the types specified by this module.
Convert Java objects to RDF
Runs a SPARQL select query and binds result variables for each matching result set. Strings bound to variables in the SELECT clause will be passed to a TBL spellchecker, which will parse the string into individual words and return triples representing each word from the string not in the dictionary. Each word returned is represented as an instance of the class http://topbraid.org/spellcheckresults#SpellResult with properties inputString, foundError, mispelledWords, and suggestions, all with the same prefix as SpellResult, http://topbraid.org/spellcheckresults#. The value of the suggestions property is an rdf:Bag with five suggested replacements for the word. In the checked content, terms in all upper-case such as acronyms are ignored.
The spellcheck dictionary is included with TopBraid Live (both Personal and Enterprise Server). Words can be added to the dictionary through the sml:UpdateUserWordDictionary module.
Check spelling
The SELECT query that delivers all the literals that shall be spell checked.
1
1
The name of the variable that will hold the constant. Default: text.
text
The constant value (either a resource or a literal).
Binds a variable with a given RDF node.
Bind with constant
Executes a SPARQL Select query and creates a single long text string by concatenating all result variable bindings. This can be used, for example, to create a single "fullName" value from "firstName" and "lastName" properties (in which case the order of variables in the SELECT clause is relevant. Another use case is to build a single long string from multiple property values of the same kind, e.g. to concatenate all text bodies of all RSS items in a newsfeed. The resulting text can then be further processed by text processing modules such as text miners.
text
The name of the output variable that will contain the concatenated text string. Default: text.
true
An optional separator that will be inserted between the text units.
The SPARQL Select query that will deliver the individual values that shall be concatenated.
Concatenate text
true
Update user word dictionary
1
1
The SELECT query that delivers action (remove / add) and the literal that shall be removed / added from / to the dictionary of user specified words. <http://topbraid.org/spellcheckresults#removeWord> is used to specify remove action and <http://topbraid.org/spellcheckresults#addWord> is used to specify add action.
SM Module for adding and removing words from the dictionary of user specified words. Words in the dictionary of user specified words are ignored by the CheckSpelling module.
Import news feed
The URL of the newsfeed.
Connects to a newsfeed specified by a URL and returns its content as RDF triples. Supported formats are Atom 0.3, Atom 1.0, RSS 0.91, 0.92, 1.0, 2.0. The url string may contain variable placeholders such as {?keyword} to insert variable bindings.
Microsoft SQL Server
Creates a geographical map displaying resources from one or more given SPARQL queries. Resources can be displayed on a map if they have geo:lat/long values as objects. Currently only supported within TBC.
A SPARQL Select query delivering the subjects that shall be displayed. If empty, all subject with a value for geo:lat will be displayed.
0
Create map
The (template) string to append to the variable value.
Appends a given text (possibly containing template expressions, sml:template) to the value of a given variable (sml:variable) and binds the concatenation of the old value plus the new text to the same variable. This can be used to incrementally build up a string.
The name of the variable to append to.
text
Append text
error
The name of the output variable that shall hold the error message.
1
1
The head of the script to execute. Must have a single end module.
Runs a sub-script (sm:body) and catches any errors (Java Exceptions) that happened within it. Normally, the SPARQLMotion engine exits on hitting any Exception, but this module provides a level of error handling. If an error occurs, then the result variable (sm:outputVariable) will contain the error message, and the result graph will be the same as the input of the module itself. Otherwise, the output graph will be the last module of the nested body script, and any variable bindings from the body will be applied to the next modules.
Catch exceptions
Connects to an Oracle 11g RDF database and writes the input triples into it.
Note: This is a low-level system module. The preferred way of writing to databases is using sml:PerformUpdate.
The URL of the database.
the mode of export to use
Export to Oracle RDF database
The user name to log in with.
true
The password to log in with.
true to replace all triples currently in the database.
true
The internal Oracle name of the database.
the label of the button under the form
true
the title of the edit form
true
the class of the instance to edit
Display edit form
Displays a form that enables end-users to edit an instance of a given class. The new triples will be added to a run-time RDF graph and can then be queried by the next modules in the script. Note that the output RDF graph may contain other triples (such as imports or form declarations) which should be ignored - the only "save" triples to get are the direct property values of the resource specified by outputVariable.
This module is currently supported by TBC and TBE.
the name of the variable that can be used to access the edited instance in the next modules
instance
Create SPIN Result Set
The SELECT query to evaluate.
The name of the output variable that will point to the new spr:Table resource.
table
Converts the result set of a given SPARQL SELECT query (sml:selectQuery) to an SPIN result set (SPR table resource). The resulting resource can then be queried using the SPR functions. The output graph of this module contains only table triples.
Bind with selected resource
Deprecated since 2.0.0/TopBraid 3.0: use sml:SelectedResourceArgument in a function definition instead.
resource
The name of the variable that will point to the currently selected resource. Default: resource.
1
An optional ASK query that can be used to determine whether this input is assigned for the given resource. The query will be executed with the outputVariable (default: ?resource) already bound. For example, if this returns true for the selected resource, then TopBraid Composer would display the sml:ReturnXY nodes in drop down menus for the resource.
Evaluates an ASK condition and stops the execution of the script and reports an error if the condition is false. This module is particularly useful for web services that simply cannot execute if unexpected situations are encountered. The module will simply pass through all variable bindings and RDF triples if no errors are found.
The ASK query that must return true.
1
1
the error message
true
Assert true
Import current RDF
Depending on the context, this module delivers different results.
When called from a TBE session, this will return the session's RDF graph.
When called from TBC, this will also return the RDF graph of the currently open file. In many use cases this will include the script itself, unless the script is a background service such as an sml:TrackChanges script.
When called from a user-defined SPARQLMotion/SPIN Function, this module will return the context graph, which is the graph that the surrounding SPARQL query will currently operate on.
When called as a TopBraid Live (stand-alone) web service, this module will throw an exception because there is no current graph available.
xml
The name of the variable that will be bound in each iteration.
The body to execute in each iteration.
1
1
Evaluates an XPath on a given XML document (or node) and executes a given body for each binding. The outputVariable will be bound in each iteration of the loop, bound to the XML node. The main use case of this module is in combination with sml:BindByXPath: IterateOverXPath walks through a list of top-level nodes and sml:BindByXPath is then used to extract individual values in each iteration.
Iterate over XPath
The XML node (document or element) to operate on.
The XPath to evaluate.
The path to the output file. The path can be relative to the current script's folder (e.g., myFolder/test.xml) or absolute to the workspace root /myProject/myFolder/test.xml.
Creates an XML file from the value of the input variable.
The XML document that shall be written to the file.
Export to XML file
The source XML variable
Convert XML by XSLT
xml
The generated XML string variable. The recommended module to export or return the value of this variable is sml:ExportToXMLFile or sml:ReturnXML.
The string variable holding the XSLT script
Converts an XML document into another XML document using XSLT. The source XML document is either a XML or string variable. The target XML document is a string variable. XSLT script is provided as a string.
Loads an XML file, specified by a file path and binds the resulting document as an XML DOM tree to the specified output variable. This module is often the starting point of XML processing steps such as XSLT transformations or XPath queries.
The path to the XML file in the workspace. The path can be relative to the current script's folder (e.g., myFolder/test.xml) or absolute to the workspace root /myProject/myFolder/test.xml.
xml
The name of the variable containing the XML data. Default: xml.
Import XML file
Apply Pellet
Applies the Pellet inference engine on the input triples.
Bind with parameter
Deprecated since 2.0.0: Web Services are now defined like user-defined functions and SPIN functions, and the parameters are instances of spl:Argument.
true
true
Applies the rules specified as values of the jena:rule property in the source ontologies. Furthermore, all SWRL rules (swrl:Imp) will be converted to Jena rules before execution. The inferred triples will be added to the input.
Apply Jena rules
A UISPIN document to render. This document may reference the bound variables of this module.
Return UISPIN document
Creates a UISPIN document using the current variable bindings and returns the resulting document as XHTML or SVG to the caller of the web service.
Note that in order to insert a UISPIN view for a given resource (using ui:instanceView etc), you can use the snippet <ui:resourceView ui:resource="{= ?varName }" />.
Also note that in order to use HTML or SVG tags in the sml:view, you will need to import the html.rdf or svg.rdf from the UISPIN ontologies into the script.
true
Overrides the default mime type returned by the UISPIN engine.
true
True to only create a UISPIN snippet, e.g. without head/body.
Iterate over SQL
true
The password for the database.
Repeats a given sub-script for each matching result set of a given SQL Select query. The system will do a mapping of SQL values to suitable XSD datatypes.
The start of the sub-script is specified by the body property, and the input RDF of the body is the same as the input of the iteration module itself. The result variables of the Select query will be bound in each iteration of the loop.
The result of this module are the accumulated triples from the end nodes of the body scripts. No internal variable bindings of the body will be used outside of the body.
The SQL SELECT query to send to the database.
1
1
The body of the iteration loop.
The user name for the database.
true
The URL of the database.
The type of the database.
The URL to post to.
Post request
Sends a POST request to a web server and binds the result stream with the outputVariable. By default, the request will not include any variable bindings. In order to pass in any other parameters, you need to subclass the sml:PostRequest class and declare the additional arguments as spin:constraints. The system will then iterate over all arguments (other than url and outputVariable) that are declared for this type.
The name of the output variable to bind the result with.
response
the result, usually passed in from a previous module
Return node
Returns an RDF node as a result of a script. This module is typically used as exit point of a user-defined SPIN function and web service. The sm:returnModule of the function will point to this.
Collect garbage
The base URI of the RDF model to "forget".
Collects "garbage" to clean up memory from RDF models that are no longer used. Currently, this requires specifying the base URI of a graph that has been previously loaded. Note that the use of this module is not safe in a multi-user setting, and should only be used if you know what you are doing.
Serves as an entry point for scripts that are triggered by incoming emails. If a new message has been detected for the provided account, then this module will produce triple representing the new message as an anonymous instance of the email:Message class.
Track EMails
The email account to track messages at.
The path to the folder to get (e.g. "INBOX")
Import GRDDL
Imports RDF triples from a GRDDL-enabled web page.
The URL of the GRDDL source document.
the named graph URI
true
The database URL.
Import SDB
true
The password of the connection.
true
The user name of the connection.
The database type, such as Oracle.
Connects to an existing Jena SDB database.
Note: This is a low-level system module. The preferred way of operating on existing SDBs is using sml:ImportRDFFromWorkspace.
NTriple
Diff
The module representing the old graph. Must be a predecessor of the current module to ensure that the module has been executed before.
Returns a diff graph between an old graph and a new graph. This module is related to the old graph with sml:oldGraph and the new graph with sml:newGraph properties.
The module representing the new graph. Must be a predecessor of the current module to ensure that the module has been executed before.
text
The variable that will contain the resulting matrix as an xsd:string literal. Default: text.
1
A SPARQL Select query that delivers the resources or literals that define the rows. The query should have a single result variable, and this variable should be used in the cell query.
1
A SPARQL Select query that is executed for each cell in the matrix. The query should reference the result variables of column and row queries (these will be bound automatically by the engine).
1
1
Create matrix
Creates a matrix (spreadsheet) and binds it as a text value to a given output variable.
The rows and columns of the matrix are specified by two SPARQL queries. These queries must deliver variable bindings to enumerate the resources that shall be used as rows and columns. The cell values are then computed using a third query (cellQuery) that should reference the bound variable names from the row and column queries.
A SPARQL Select query that delivers the resources or literals that define the colums. The query should have a single result variable, and this variable should be used in the cell query.
1
1
Send emails
Sends one or more emails. In a typical scenario, previous steps such as sml:ApplyConstruct have created instances of email:Message. The body of the emails could be created using sml:CreateTextFromJSP. A SPARQL Select query is then used to select those messages that shall be sent out, based on the given server parameters.
The SMTP server that shall be used to send the emails from.
1
1
A SPARQL Select query that binds instances of email:Message to send out.
Export to TDB
true
True to overwrite any pre-existing database at this location.
The path to the TDB database.
The base URI for the TDB repository.
Export the input RDF triples to a given Jena TDB database.
Note: This is a low-level system module. The preferred way of writing to databases is using sml:PerformUpdate.
The text that shall be sent to the Calais service.
Runs the OpenCalais web service to extract RDF entities from text. The result will be the input triples plus the extracted triples (instances of the Calais ontology classes).
Call Calais
Release lock
Releases any exclusive system lock previously received using sml:RequestLock.
Request lock
Requests a lock to get exclusive access to the TopBraid platform. This will make sure that no other thread is executing, so that the following modules in the script can proceed without risking interrupts or concurrent modification exceptions. When reached, the module will wait until all other threads have finished, then continue execution. The lock will be released if the script terminates or sml:ReleaseLock is reached.
Please use this module with care and release the lock as quickly as possible to avoid contention issues. Other concurrent requests may need to wait until the script has been finished.
Loads an Excel file into instances of the TopBraid spreadsheets ontology - each non-empty cell becomes an instance of ss:Cell. In a typical scenario, the resulting cell instances are passed into other modules (such as sml:ApplyConstruct) to convert the raw data into a more useful format. This module provides the functionality that is accessible from TBC, as described in Help > Import > Import Excel File into Spreadsheet Ontology.
This module is distinct from the Semantic Tables importer, which can be used with sml:ImportRDFFormWorkspace to also import Excel files. The latter is better suited for spreadsheets consisting of regular tables, while this module here is optimized for cases in which the Excel file is not well-structured and each individual cell has a different meaning or role.
The naming pattern for the generated instances. This can contain static characters or placeholders for columns. For example Person-%1 will create names that consist of the static string "Person-" and then the value of the first column.
true
Creates an RDF graph from a tab-separated spreadsheet which is specified from a given string variable. In a typical use case, this will be used after sml:ImportTextFile, which binds the variable text which is also the default input variable of this module. For very large files that cannot be loaded into memory, the module provides the option to specify a file directly using sml:sourceFilePath.
Note that TopBraid supports multiple spreadsheet importer algorithms, including Semantic Tables and the Excel cell importer (sml:ImportExcelCellInstances). This module provides the functionality that is accessible through the TopBraid Composer Spreadsheet import wizard (Help > Import > Import Tab-Delimited Spreadsheet File).
The prefix that shall be used for the generated property names. Only used if no qname is specified for a column property and if a new graph is created from the spreadsheet, i.e. importToInputGraph value is false.
true
true
The spreadsheet's text that shall be converted. If sml:sourceFilePath is set then this value is ignored.
true
An optional file path to the spreadsheet. If this is specified then the module will directly do streaming loading from the given file. This should make it possible to handle files of arbitrary size.
The base namespace of the target schema.
true
If true, it replaces special characters, i.e. characters that cannot be imported by default to create a resource URI, with an underscore. If false, these characters are ignored during import.
Convert spreadsheet to RDF
The canonical name of the text encoding of the spreadsheet file. If no value for this property is given, then the default JRE encoding is used. If an encoding value is given for this property, then the spreadsheet file will be evaluated using this value. The supported encodings can be found at the website: <http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html>
true
true
If true, it imports special characters, i.e. characters that cannot be imported by default to create a resource URI. If false, these characters are ignored during import.
The optional name of the target class. If this value is unspecified, then cell (0, 0) of the spreadsheet is used instead. This value can be a localname, a qname or a URI string. If it doesn't exist, then it is created.
true
true
If set to true, then the import will attempt to reuse properties defined in the input RDF graph for the column-to-property mapping.
Import Excel cell instances
The path to the Excel source file in the workspace. The path can be relative to the current script's folder (e.g., myFolder/test.xls) or absolute to the workspace root /myProject/myFolder/test.xls.
Loads an RDF file from the workspace, based on its base URI (or a path to the file). If the file is already open, it will reuse the currently open model (including any changes that it has compared to the persistent version). The system will use which ever physical file has been registered for the given base URI. This is the recommended module to load any file type supported by TopBraid, including file serializations (N3, Turtle, RDF/XML and N-TRIPLE), data connectors, XML files (Semantic XML), Excel 2003 .xls files (Semantic Tables), etc. If the file being opened is a file, the file is loaded into memory. If it is a data connector (RDF or relational back-end), the data source is opened, but no data is loaded into memory.
An (optional) file path pointing to the file that shall be opened. The system will look up the base URI of that file and then open that base URI. This means that if the workspace contains multiple copies of that base URI then it may actually load a different file than the one specified here (it will always use the primary file).
true
Indicates whether owl:imports shall be ignored. If false, then the union of the base graph plus its (transitive) imports will be returned.
true
false
true
The (optional) base URI of the model to open. Either this baseURI must be specified or the sourceFilePath. If both are present then the baseURI has priority.
Import RDF from workspace
Converts RDF into XML using the Semantic XML (sxml) ontology for the round-tripping. The resulting XML will be bound to the specified output variable. Note that this requires the RDF model to contain an SXML root document element - this function does not work with arbitrary RDF data! For more, see Help > Import and Export > Creating, Importing, Querying, Saving XML documents with Semantic XML.
xml
The name of the variable that will hold the resulting XML data. Default: xml.
Convert RDF to XML
Converts an arbitrary XML input model into an RDF graph using the Semantic XML mapping approach. For more, see Help > Import and Export > Creating, Importing, Querying, Saving XML documents with Semantic XML.
Convert XML to RDF
The XML document that shall be converted to RDF.
The base URI of the new RDF (for the creation of the new class and property names).
An (optional) type indicator for the Semantic XML conversion. Current supported values are "XHTML" (treats the input as HTML source, and may run a tidy algorithm in case the HTML is not well-formed XHTML).
true