TopQuadrant - SPARQLMotion - Example SendEmailService
SPARQLMotion Example SendEmailService
This SPARQLMotion script allows users to send a selected Email. The email must be an instance of email:Message (or a subclass thereof).
This SPARQLMotion script can actually be used as an extension of the TopBraid Composer tool itself. If the script is registered with TopBraid, then the user can call the script below from the context menu of any email:Message instance. Note that the script file has the ending .sms.n3 - this instructs TopBraid to add it to the service registry. It is therefore enough to download the file into a project in the Composer workspace (and possibly open the script and re-run Scripts > Refresh/Display SPARQLMotion services...).
If you want to build your own email message, then in a separate ontology, first import email.owl from the Navigator at TopBraid > TBC > email.owl. And then in this ontology, create an instance of email:Server with the outgoing server (SMTP) parameters of your email account. Finally create an instance of email:Message, provide the email:from, email:to, email:subject and other values, and go to Resource > Send this message. If you would like to receive the email message in your inbox, at the instance of email:Message, please specify the email:to value with your email address.
The script demonstrates several aspects of SPARQLMotion, including branching (if-then-else), user input, external input, binding configuration variables at run-time and creating custom services.
Download in N3 format (2008-03-13, requires sparqlmotionlib 1.1.0)
Details on the steps (in order to execution from top to bottom) follow.
|Current RDF (type: Import current RDF) simply takes the currently selected model as starting point. In TopBraid Composer this would be the model that is currently open and has the focus. This is the model that contains the runtime data, i.e. the email message that shall be sent.|
|Test if multiple servers exist (type: Branch by ask) performs a SPARQL ASK query to determine whether there are at least two different instances of email:Server present. Depending on the outcome, this first executes either the if or else branch and then continues with the next module. Both branches (if and else) bind the variable server that will be passed into the rest of the script.|
|Select server (type: Select instance) will be executed if the ASK query from the branch above returns true. In other words, if at least two email:Servers are present, then ask the user to select one. This will pop up a selection dialog in which the user can pick one instance of the email:Server class. The selected server instance will be bound to the smtpServer output variable.|
|Get first server (type: Bind by select) is executed when the ASK query in the branch module is evaluated to false. So if there is just one email:Server present, then we just get it using a SPARQL SELECT query and assign the result into the variable smtpServer.|
|Selected resource (type: Bind with selected resource) is an external entry point into the script. It will be initialized by the execution engine and will bind the currently selected resource with the specified output variable resource. Modules of this type can optionally also define an ASK query that will be evaluated by the environment prior to executing the script. This ASK query serves as a pre-condition that determines whether the script shall show up as a service in the context menu of the currently selected resource. In this case, the ASK query checks whether the resource has a value for the email:to property to distinguish Email messages from other instances.|
|Send eMail (type: Send emails) does the actual work in this script: it sends the email specified by the input variable resource. The select query defines which email(s) shall be sent, and in this case we only get the value of the resource variable, which is already bound by the predecessors of this module. The smtpServer property is part of the Send emails module class and must point to a email:Server instance. Since we do not know this value at edit time of the script, we leave it empty so that it will get its values from the variables of the predecessor modules at execution time. Both branches of the if-then-else block above it bind a variable called smtpServer and this value will be used here.|
|Get subject (type: Bind by select) runs a simple SPARQL SELECT query to bind the variable subject with the subject of the email message that has just been sent. The resulting subject line will then be passed into the next module to create a success message.|
|Create success message (type: Bind literal variable) takes the subject from the previous step and inserts it into a string variable called text.|
|Send this Message (type: Return text) is the exit point of the service. It takes the value of the text variable and displays it to the end user. The return module also identifies the service to the tool, and defines the label that will be used in the drop down menu.|