ModelMaker Users Guide

8/12/2019 ModelMaker Users Guide

1/25

Kap

owMashupSe

rver6.4

ModelMakerUsers Guide


2/25


3/25

ModelMakerUsers Guide


4/25

Copyright 1999-2007 Kapow Technologies

http://www.kapowtech.com

All rights reserved.


5/25

CONTENTS iii

Contents

INTRODUCTION ........................................................................................ 1What is ModelMaker? ..........................................................................1Before You Read On ............................................................................1Other Resources.................................................................................1

MODELMAKER BASICS ............................................................................... 2Objects .............................................................................................2Attributes ..........................................................................................2Domain Models...................................................................................2

MODELMAKER USER INTERFACE ................................................................... 4TUTORIAL:CREATING A DOMAIN MODEL ........................................................ 5

Creating the Object.............................................................................5Adding Attributes................................................................................6Validating the Domain Model ................................................................7Previewing the Object .........................................................................8Saving the Domain Model ....................................................................8Creating the Database Table ..............................................................10

EXAMPLE DOMAIN MODELS ....................................................................... 13FEATURES IN DEPTH................................................................................ 14

Database Output Objects Explained.....................................................14Validating Domain Models ..................................................................15Configuring Objects .......................................................................... 15Configuring Attributes .......................................................................16Modifying an Existing Object ..............................................................17Creating and Deleting Database Tables ................................................18

INDEX.................................................................................................. 19


6/25


7/25

INTRODUCTION 1

IntroductionWhat is ModelMaker?ModelMaker is an application for modeling the objects used by a robot, such asthe objects that the robot extracts and the objects that it accepts as inputobjects.

Before You Read OnBefore you proceed to the next chapter, make sure that you have installedModelMaker correctly as described in the Installation Guide.

Other ResourcesAdditional, mostly referential documentation on ModelMaker is available in theModelMaker entry in RoboHelp, which is accessible from the Help menu inModelMaker.

You should also check out the support site at this URL:

http://support.kapowtech.com/


8/25

2 MODELMAKER USER'S GUIDE

ModelMaker BasicsModelMaker is an application for creating the objects that are used by robots.This chapter introduces you to the key concepts in ModelMaker.

With ModelMaker, you are able to design objects that are modeledafter real-world data. In the most common case, an object is designed to hold the datathat a robot collects or extracts from a data source. In RoboMaker, you areable to build your robots using the objects you create with ModelMaker.

See the RoboMaker Users Guide for more information about how RoboMaker

uses the objects created by ModelMaker.

ObjectsObjects can be used by robots for different purposes. For example, a robot canextract objects, return error or status objects, or it can receive objects asinput, known as input objects.

An object has an object typethat determines how the object can be used.

The following object types are available:Input Object this is an object that can be given as input to a robot, to

provide information that the robot needs to perform its task.

Output Object this is an object that can be extracted by a robot. Thistype can also be used for other objects to be returned by a robot,such as error or status objects.

Database Output Object this is an object that can be extracted by arobot and stored in a database.

In essence, objects are used as data carriers, either as input to a robot in theform of input objects, or as output from a robot in the form of output objectsor database output objects.

AttributesAn object has a number of attributes. The attributes are where the data isheld inside an object. For example, a news article object could have attributessuch as title, author, date, and content. An attribute has an attribute type,

which determines what kind of data the attribute can contain. For example,the title attribute of a news article object could have the type Short Text.There are many different attribute types available, such as Short Text, LongText, Character, Integer, Number, Date, Boolean, and Binary. The data in anattribute is called an attribute value.

Domain ModelsObjects are organized into domain models. A domain modeldefines one ormore objects. A domain modeltypically models a specific domain, such as


9/25

MODELMAKER BASICS 3

news, stocks, or airline information, by defining the objects that are relevantfor that domain.

ModelMaker is an application for creating domain models, just as RoboMaker isan application for creating robots. In ModelMaker, you are always working ona current domain model.

A domain model must satisfy certain requirements to be used in the otherapplications of Kapow Mashup Server. The domain model is said to be validifit satisfies these requirements. Checking whether a domain model is valid iscalled validatingthe domain model.


10/25


ModelMaker User InterfaceThis chapter gets you started with using ModelMaker, by introducing you tothe user interface of the application. The main window of ModelMaker is shownbelow:

Object List

Attribute Table

Add, Remove, and Configure Attributes

Add, Remove, and Preview Objects

Figure 1: ModelMaker Main Window

To the left in the window is the Object List. This is the list of objects in thedomain model that you are working on. You can add new objects, removeobjects, change the order of the objects, and preview objects (to see how they

will appear in RoboMaker), using the buttons below the Object List.

The currently selected object is configured in the right part of the mainwindow. Among other things, you can configure the attributes of the object.This is done in the Attribute Table. You can add new attributes, removeattributes, change their order, and configure attributes using the buttonsbelow the Attribute Table.


11/25

TUTORIAL:CREATING A DOMAIN MODEL 5

Tutorial: Creating a Domain ModelLet us create a domain model containing a news article object that we can usefor extracting news articles from web sites.

Creating the ObjectStart ModelMaker and choose Create a new domain model.... ModelMakerwill start with an empty domain model. Add a new object to the domain model

by clicking the button below the Object List. Choose Database OutputObject and click OK. This creates an object that can be extracted by a robotand stored in a database.

The ModelMaker Main Window should now look like this:

Note that a number of attributes have already been added to the object, suchas robotId, robotRunId, etc. These attributes are for administration purposesand are required for a database output object. Therefore, you should notremove or change these attributes. They are shown in gray as a reminder thatthey are required and should not be modified.


12/25


Adding Attributes

Now, let us add a title attribute to the article object. Click the button belowthe Attribute Table. The Attribute Configuration window will pop up. Configurethe attribute as shown below:

Click the OK button. As you return to the main window, notice that the titleattribute has been added to the Attribute Table.


13/25


Add another attribute for the body text of the article, and configure it asshown below. Note that you should set the attribute type to Long Text:

Click OK to return to the main window. Of course, a real-world article objectwould have more attributes than these, but let us skip those in this example.

Validating the Domain ModelTry validating your domain model by clicking the icon. You should see thismessage:

As you can see, your domain model is not yet valid, since you havent given

the object a name. Therefore, set the name of the object to MyArticle.


14/25


Then try to validate the domain model again by clicking the icon. Now youshould see this message:

The domain model is now valid.

Previewing the ObjectIn order to see what the object would look like when inspected in RoboMaker,you can preview it by pressing the button below the Object List. This will

show the window below:

This can be especially useful if you want to verify that attributes that are notmarked as Visible are indeed hidden inside the object. Note that in our case,

only our two new attributes are shown. The six attributes that were grayedwhen we created our database output object all have the Visible propertyunchecked in their configurations.

Saving the Domain ModelTo make your domain model accessible to your robots, you must save thedomain model in the robot librarythat the robots belong to. Normally, this isthe robot library of the current robot project, which is the robot project that


15/25


you are currently working on. For more information on robot libraries androbot projects, see the RoboMaker Users Guide.

To save your domain model, click the icon, and choose the folder to savethe domain model in. ModelMaker will default to the robot library folder of thecurrent robot project, which is where we want to save the domain model inthis tutorial. Enter MyArticle as the file name and click Save. Your domainmodel will now be saved as the file MyArticle.model.

Now, let us check that the domain model is accessible in RoboMaker. To use anewly created domain model in another Kapow Mashup Server application thatis already running, you must reload the domain models in that application by

clicking the icon in the application. If you already have RoboMaker running,reload its domain models now to make it use the new domain model,otherwise start RoboMaker now.

In RoboMaker, go to the Output Objects tab of the Objects View, located inthe lower right corner of the RoboMaker Main Window, and shown below.


16/25


Click the Add/Remove... button to open the Add/Remove Output Objects

window. Click the icon to add a new output object to the robot. You should

now be able to select your MyArticle object in the drop-down box. Do that,and then click OK to close the window. You can now view your object in theOutput Objects tab, which should look like this:

As you can see, the MyArticle object has the title and body attributes that youdefined in ModelMaker, and looks as when we previewed it in ModelMaker.Note also that the administration attributes (robotId, robotRunId, etc.) are notvisible or accessible.

Important Note:You cannot have two objects with the same name in thesame robot library, even if the objects are in two different domain models inthe robot library.

Creating the Database TableIf you want to be able to store your database output objects in a database,you should create matching tables in an appropriate database. ModelMakercan assist you in creating these tables. If your system administrator has notyet set up a database connection for you, you should skip this portion of thetutorial.


17/25


To see how to create the database table for the MyArticle object, select

Create Database Table ( ) in the Tools menu of ModelMaker. This will open

the Create Database Table Window. Select the MyArticle object in theObject property, as shown below:

Next, select the database name along with the relevant database vendor typefor that database. Click Generate SQL. This will generate a suggestion for anSQL statement for creating the table, similar to the one shown below:

You can edit the SQL statement to fit your needs, and then execute it or saveit. However, in this tutorial, just click Close in the two windows to close themwithout doing anything with the statement.


18/25


This completes the tutorial. Youve now learned how to create a new domainmodel with an object from scratch, and make it ready for use in robots you

create with RoboMaker.


19/25

EXAMPLE DOMAIN MODELS 13

Example Domain ModelsThe installation includes a number of example domain models representingsome common domains. These example domain models are located in theProject/Library/Examples subfolder in the installation folder.

If you want to create an object with the same name as an object in anexample domain model, you need to remove the example domain model,since a robot library cannot contain multiple objects with the same name.Alternatively, you can use another project. Please see the Installation Guide

for information on how to change the current project.


20/25


Features in DepthThis chapter discusses the features of ModelMaker in more detail. For morespecific information about configuring domain models, objects, and attributes,please consult the online RoboHelp entries for ModelMaker.

Database Output Objects ExplainedIf your robot uses a database output object, it will need to handle the returnedobjects in some way. Typically, the objects will be saved in a storage location,

such as in a file or in a database. This way, other applications will then be ableto access the data that has been collected by the robot.

In order to be able to successfully store and retrieve objects, the followingattributes are included in all database output objects:

Attribute Name Attribute Type

robotId Integer

robotRunId Integer

refindKey Refind Key

firstExtractionDate Date

latestExtractionDate Date

extractedInLatestRun Boolean

When storing an object in a storage location, an important issue is what to doif the storage already contains the particular object. A simple mechanism isused for refinding existing objects in storage and updating these instead ofinserting multiple copies of the object. When a database output object is readyto be added to storage, a search is made for an existing object with the same

refindKey in the storage. If such an object exists, it will be updated, and ifnot, the extracted object will be inserted. You must select the attributes toinclude in the comparison when refinding objects, by setting the Part ofRefind Key option of those attributes.

As for the remaining attributes required, the firstExtractedDate is the dateand time when the object was extracted for the first time, and the

latestExtractedDate is the date and time when the extracted object wasmost recently inserted or updated. The extractedInLatestRun attribute willbe true if the object was extracted in the latest robot run.

The way in which your extracted objects are physically stored depends on theStorage Environmentthat is used when the robot is run. See the Robo-Server Users Guide or the RoboRunner Users Guide for more on running


21/25

FEATURES IN DEPTH 15

robots with environments. Note that not all storage environments supportrefinding of objects.

In the case of saving a database output object to database storage using theDatabase Storage Environment, it is of course necessary that the appropriatedatabase table exists in a database that is available. This means that it is arequirement that the table contains columns that match the attributes listedabove, as well as columns for all of the attributes specific to the object.

See the Creating and Deleting Database Tables section for more informationon how ModelMaker can assist you in setting up the appropriate databasetables. Consult the Installation Guide for more information on setting up

database connections. For more information about environments, see theRoboRunner Users Guide and the Environments section of the RoboRunnersection in the online RoboHelp.

Validating Domain ModelsA domain model must satisfy certain requirements to be used in the otherapplications of Kapow Mashup Server. For example, each object in a domainmodel must have a unique name. A domain model that satisfies all the

requirements is said to be valid. Checking that a domain model is valid iscalled validating the domain model.

Every time a domain model is changed in ModelMaker it is automaticallyvalidated. This includes any modifications to the objects in the domain model,as well as any of the attributes on those objects. In the title of the mainwindow of ModelMaker, you can see if the domain model is valid or not. If thedomain model is invalid, select Validate Domain Model in the Edit menu or

press and you will be presented with a message box explaining the reason.

Configuring ObjectsWhen working with an object within a domain model, it is important that youconfigure all of the relevant properties of the object. Otherwise, the domainmodel will be invalid, or the object will not behave as expected when used inRoboMaker. To configure an object, you must first select it in the Object List.The selected object is then displayed in the right side of the main view ofModelMaker, where you can make changes.

All objects within a domain model must have a valid name. If a domain modelcontains only one object, it is common practice to give the same name to boththe domain model and the object. This will not cause any problems, and can infact help simplify things in many cases. You can set the name of an objectabove the Attribute Table in the object configuration view.

Also, as mentioned previously, all objects must have an object type, whichindicates how the object will be used. You can choose the object type for anobject using the Type drop-down box below the Attribute Table.


22/25


Configuring Attributes

The attributes within an object must also be correctly added and configured inorder for the object to be valid. You must specify both a name and a type foreach attribute. The available attribute types are shown in Figure 2.

Attribute Type Description

Integer An integer, e.g. 12.

Number A number, e.g. 12.345.

Boolean A boolean value, i.e. either "true" or "false".

Character A single character, e.g. "A".

Short Text A short text. Will be displayed in a one-line textfield.

Long Text A long text. Will be displayed in a multi-line textbox.

Password A password. Will be diplayed in a password fieldthat shows asterisks instead of the characters inthe password.

HTML An HTML clip. This is the same as a Long Text,except that you can preview the clip in a browserwindow.

XML An XML document. This is the same as a LongText, except that only well-formed XML

documents are allowed.

Date A date. The date must be of the form yyyy-mm-ddhh:mm:ss.n, e.g. "1992-04-25 10:33:06.0".

Binary Binary data, i.e. any sequence of bytes.

Image An image. This is the same as Binary Data, exceptthat you can preview the image.

PDF A PDF document. This is the same as Binary Data,except that you can preview the PDF document.

Session A session (containing cookies, authentications,etc.).

Currency A currency code, as defined by the ISO-4217standard, e.g. "EUR" for Euro.

Country A country code, as defined by the ISO-3166standard, e.g. "DE" for Germany.


23/25

FEATURES IN DEPTH 17

Attribute Type Description

Language A language code, as defined by the ISO-639standard, e.g. "de" for German.

Refind Key A special refind key used for refinding objects.

Figure 2: Attribute Types

The Refind Key attribute type is used when storing database output objects see the section Database Output Objects Explained for more information.

An attribute has a number of other configurable properties, such as whetheror not the attribute is visible from within RoboMaker, and whether or not theattribute is required to contain data before the object can be stored. Refer tothe online RoboHelp entries in ModelMaker on attribute configuration for moreinformation.

Modifying an Existing ObjectIf you need to change an object after you have written robots that use it, you

need to be careful. Your robots might stop working if you do somethingwrong.

You should never perform any of the following changes to an object that isalready used by existing robots if you do, you will not be able to use theobject in those robots (however, the robots may still be loaded without theobjects that were modified):

Change the name of an object. Change the type of an object. Delete an object. Remove or rename an attribute that is assigned a value different from

its default value in the Robot Configuration.

Change the type of an attribute that is assigned a value different fromits default value in the Robot Configuration to a type than is notcompatible with the assigned value.

You may perform the following changes to an object, but some of the existing

robots may generate errors when they are executed (you can subsequently fixthese errors):

Change the name of an attribute. Change the Required property of an attribute from false to true. Add a new attribute that has the Required property set to true. Delete or rename an attribute that has its default value in the Robot

Configuration.


24/25


Change the type of an attribute that has its default value in the RobotConfiguration.

You can always make the following changes, without affecting the existingrobots:

Change the Required property of an attribute from true to false. Change the name and revision of a domain model. Change a comment (no matter where). Add a new object with a new name. Add a new attribute that has the Required property set to false.

Creating and Deleting Database TablesIf you want to store your extracted objects in a database, you should creatematching tables in the database. ModelMaker can assist you in creating thesetables. It does so by examining the object you have created, and generatingSQL that is appropriate for creating a new database table.

In the Tools menu, select Create Database Table ( ) to open a window whereyou can choose the name of your database (as defined in Settings see theInstallation Guide), the type of database, and the object that you want tocreate the table for. By clicking Generate SQL, you will be shown a suggestionfor an SQL statement for creating the table, which you then have the option tomodify as well as execute or save.

The SQL shown is a recommended suggestion by ModelMaker you canchange the statement to fit your needs, if required. For example, you mightchange the column type for a Short Text attribute from "VARCHAR(255)" to"VARCHAR(50)" in order to conserve database space, or you could add an

auto-incrementing primary key. However, under normal circumstances, youshould notmodify the table name or any of the column names, nor removeany of the columns.

You can also delete an existing table in the database using the Drop Database

Table ( ) command under the Tools menu.


25/25

INDEX 19

Index

Aattributes, 2

adding to object, 6

configuring, 17

types, 2, 17

Ccurrent robot project, 9

Ddatabase output object, 2

database tables

creating, 10, 19

deleting, 19

domain models, 3

saving, 9

validating, 7, 15

Eexample domain models, 13

Iinput objects, 2

MModelMaker, 1, 2

Oobjects, 2

adding attributes, 6

configuring, 15

creating, 5

database output, 2, 14

input, 2

modifying existing, 18

naming, 10

output, 2

previewing, 8

refinding, 14

storing extracted, 15

types, 2

output object, 2

Rrefind key, 14robot library, 9

SStorage Environment, 15

Vvalidation, 7, 15

Documents

ModelMaker Users Guide