Embed Size (px)
Citation preview
www.jitterbit.com
Quick Start Tutorial
The goal of this tutorial is to help new users get acquainted with the Jitterbit
Integration platform. This tutorial gives you hands-on experience using Jitterbit to
transform information between two systems. By then end of this tutorial you should be familiar with the main components of the Jitterbit integration system.
Scenario
The tutorial guides you through the creation of an integration that extracts purchase
orders from a database, transforms it into an XML document and posts that document to a local file share.
Summary of Steps
These are the steps you will take to complete the tutorial. They are also the common processes through which you will create your own operations.
1. Create a Project
2. Create an Operation
3. Create a Source
4. Create a Target
5. Create a Transformation 6. Activate and Monitor Your Operation
Create a Project
If you haven't done so already, launch the Jitterbit Integration Environment
application by choosing Launch Jitterbit Integration Environment from your Start menu. You will be given two choices:
Integration – This option allows you to create new integration projects or edit
previously saved projects.
Administration - This option allows you to jump straight into Jitterbit’s
administration tools for monitoring the integration server activity, set user/group privileges, and more.
Leave the default Integration selected. In this window you are given the following
options:
Open Existing Integration Project
Create New Integration Project Import Jitterpak
For the purposes of the tutorial, select Create New Integration Project and enter
DB to XML Tutorial as the project name. You can also specify or browse to the
www.jitterbit.com
location on your local computer where the project details should be stored. By default your project is stored in the /projects/ folder of your Jitterbit installation.
Click Create to continue. The main Integration environment now appears, with a hierarchical tree on the left.
In order to test the integration as you create it, you need to connect to the Jitterbit
Integration Server.
Click the Login button in the main toolbar to launch the Login window. Enter the
Jitterbit Server name, the User name and Password for the Jitterbit Server you wish
to connect to. You will have entered these details when you first installed the software.
Click Login to connect to the server.
www.jitterbit.com
If your connection is successful, the Server and User ID will appear in the upper right corner of the main integration window.
Create an Operation
Next, you will create an operation in which you will define and assemble all the components required to define the integration.
Right click Operations in the Project Tree and select New Operation from the popup menu.
A new operation process appears in its own New Operation tab in the right pane of
the window. Select “Transformation” for the type of operation to create. Type DB to
XML Process into the Name field.
Create a Source
A source instructs Jitterbit how to retrieve its source data for the integration - in this
tutorial the source will be a specific database. Right click “Sources” in the Project
Tree and select New Source from the popup menu.
The new source appears in its own “New Source” tab in the right pane. In the Name field, enter MyDatabase. Choose Database from the Type drop-down menu.
Click Select to the right of the Driver field and select PostgreSQL ANSI (ODBC) from the database driver list. Click OK.
1. Enter the server name or IP address for your PostgreSQL database (installed
with Jitterbit Integration Server). If you have installed the Jitterbit
Integration Server on the same machine you can enter localhost here.
2. Enter JitterbitTutorial in the Database Name field.
3. Enter the appropriate login (Hint: the default is postgres) in the Login field,
then click the Password button and enter the password for your PostgreSQL
database (Hint: you will have provided this password during installation).
www.jitterbit.com
Click the Save button in toolbar at the top of the source definition screen. Test the
source to confirm it can connect. Click the Test Connection button in the
source's toolbar. If it connects successfully close the Source tab and return to the
Operation tab.
Create a Target
Targets define where you want to put your information; in this tutorial, our target will be an XML file on a local file share.
Right click “Targets” in the Project Tree and select New Target from the popup
menu.
Your new target appears in its own “New Target” tab in the right pane. In the Name
field, enter MyXML.
Note: You will need to setup a file share on your local system in order to view the
target output for this tutorial. If you choose not to, you will be able to continue with
the tutorial and build and test the required transformation but you will be unable to
successfully run the operation and view the resulting xml file. Alternatively, you can also set up an FTP Target.
Choose File Share from the Type dropdown menu.
Enter the path to your local file share in the Path field. Enter the appropriate login and password for your file share.
Finally, we want to use the Name File(s) field to generate a unique file name that
incorporates a time stamp: enter MyPurchaseOrder_[date][time].xml, to create a file that will be unique.
www.jitterbit.com
Click the Save button in either the main toolbar or the target's toolbar.
Test your new target to confirm it can connect. Click the Test Connection button
in the target's toolbar. Close this Target tab and return to the main Operation tab.
If your new target isn't automatically loaded into your operation's Target field, select
it from the Target dropdown list.
Click the Save button in the operation's toolbar to save your work.
Create a Transformation
Transformations let you map data from your source to a target format. In our
transformation we will use two tables from the database source and map them to an
XML file. Right click “Transformations” in the Project Tree and select New Transformation from the popup menu.
The transformation wizard. In the Name field, enter MyTransformation.
Since we plan to transform from a database to XML choose Database from the
Source drop-down list and XML from the Target drop-down list. Click Next in the toolbar to continue.
www.jitterbit.com
The New Transformation: Source Setup: Database screen opens. Choose
MyDatabase in the Database Source drop-down list. Click Next in the toolbar to
continue.
All the database tables are now listed. Double-click the Order Header and Order
Detail tables in the Available Tables list to move them to the Selected Tables window. Click Next to continue.
In the Hierarchical Relationships screen you will need to join these tables. Choose the following and then click Join Tables.
The Parent (table) select "OrderHeader" The Child (table) select "OrderDetail"
www.jitterbit.com
A Join Properties window will pop up. Drag “OrderID” under the OrderHeader column
to the “OrderID” under OrderDetail to link the columns. For Join Type leave 1 to N
selected. This tells the system that there can be many OrderDetail records for every OrderHeader. Click Next in the toolbar to continue.
The SQL WHERE clause lets you optionally specify a filter for the source data. We don't need it for this exercise, so click Next in the toolbar to continue.
Now you need to select the structure of your target XML file by loading a .dtd
(document type definition) or schema file. Select the Upload an XML Structure
File radio button and click Browse. Navigate to the folder where you installed the
Jitterbit Server. You will find an example .dtd file in \Jitterbit Integration
Server\Tutorials\DbToXml\PurchaseOrder.dtd”. Select PurchaseOrder.dtd and click Open. Click Next in the toolbar to continue.
The system will warn you that there is more than one root to choose from in this
XML Structure. Scroll down and select PurchaseOrders from the list. This instructs
Jitterbit which structure in the XML file to use in this particular transformation. In
this case we will use the Purchase Order (PurchaseOrders) structure. Click Next in the toolbar to continue.
On the Options screen, leave validation checked. Click Save.
You are now ready to map the two data structures. You should now be in the main
Transformation Mapping window. Map the appropriate pairs of source and target data elements by:
Selecting a source element that you want to transform to the target.
Selecting the appropriate target that will hold data from the selected source
element.
Clicking the Map button at the bottom of the screen to save the mapping
relationship.
Alternatively, you can also drag and drop the source element onto the target element.
www.jitterbit.com
Hint: You can expand the data element trees by clicking the + button below each pane.
You will need to map the following data elements:
Source (Database) Target (XML Schema)
OrderHeader > OrderID PO > Test_Required
OrderHeader > OrderID PO > header > headerOne > PO_number
OrderHeader > OrderCreated PO > header > headerOne > order_date
OrderHeader > OrderDetail > OrderItemID PO > body > item > line_item_ID
OrderHeader > OrderDetail > Product PO > body > item > merchant_sku
OrderHeader > OrderDetail > Price PO > body > item > unit_retail_price
OrderHeader > OrderDetail > Quantity PO > body > item > quantity
Test Your Transformation. Jitterbit has the ability to test your transformations
on-the-fly by allowing you to load sample data and run a test transformation. This
process does not actually run your operation but gives you a preview of how your
data will look in the Target pane of the Transformation window. Click the
Transformation Toolkit button in the tool bar and select Test >
Transformation.
Jitterbit will require that you deploy your Source and Target to the server. Click
Deploy. Jitterbit will ask you if you want to load source data. Click Yes. A window
will pop up asking you to define an optional WHERE clause. This is not required.
Click OK. The results of your test transformation can now be seen in both the Source and Target panes.
www.jitterbit.com
Click the Save button in the transformation screen to save your changes. You now
have a new transformation definition. You can now close the Transformation window and return to your operation.
Build Your Integration Process
You have now defined your Source, Target, and Transformation. It is time to pull all
these pieces together to build your operation. To fill in your process map you have two options:
1. Drag the Source, Target, and Transformation onto the appropriate
placeholder in the process designer.
2. Right click on the placeholders in the process designer, click Select Existing and add your Source, Target, or Transformation from the popup menu.
Activate and Monitor Your Operation
Now that you've created your operation by configuring a set of definitions, it’s time
to activate it. Up until now, all the modifications you've made to your project and
operation are on a local copy of the project. Send a copy of your validated project to
the server by clicking the Deploy button in the main toolbar. If you have not
saved your operation, you will be asked to do so before deploying. Jitterbit will ask
www.jitterbit.com
which elements you wish to deploy to the server. The default is Everything. Click Deploy.
Once the project has been deployed, click the Activate button in the operation's
toolbar. Doing so will immediately place the operation into the server's queue, regardless of its schedule setting.
Assuming that the server is running, your operation will be fed into the system
queue. Click on the Queue button in the operation's toolbar to view the
operation queue. Click the Refresh button in the Queue window to update the entry:
you should see your operation disappear once it has been activated. If you do not
see your operation, it has already been process. Close the Queue window.
Note: If you have no other operations running, you will likely not see operations
sitting in the queue because they are processed quickly if the server does not have a backlog of work.
Look at the operation's log file to check the transformation's status: click the Log
button in the operation's toolbar to open the log window. If everything has
worked as expected, you will see a successful (normal) entry in the log. Otherwise,
click on any error entry to get more information on the nature of the problem.
You can now go into your local file share and view the results in the xml document
that has been created.
Congratulations! You've completed the tutorial and should now have an
understanding of how to start building your own projects and operations, and how to load them in the queue to activate their transformations.
If you have questions about this tutorial or other Jitterbit features please contact us at [email protected] or visit the Forums at www.jitterbit.com/forums.
