Apatar Quick Start Guide
Page 1 of 23
Apatar Quick Start Guide
Prepared by: Apatar, Inc. (213) 784 4915 info@apatar.com
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 2 of 23
Contents
Overview ............................................................................................................................................................. 3 Installation........................................................................................................................................................... 3 Windows.......................................................................................................................................................... 3 Linux ................................................................................................................................................................ 5 Registration ......................................................................................................................................................... 5 Application Components ..................................................................................................................................... 6 Application vs. Application no Apex ................................................................................................................ 6 Top Menu ........................................................................................................................................................ 6 Context Menu.................................................................................................................................................. 8 List of Nodes .................................................................................................................................................... 9 Work Area ....................................................................................................................................................... 9 Supported Data Sources (Connectors) .............................................................................................................. 10 Supported Operations ....................................................................................................................................... 10 Functions ........................................................................................................................................................... 11 Building a Data Integration Job (Datamap) ....................................................................................................... 12 Connectors Configuration ............................................................................................................................. 12 Operations Configuration.............................................................................................................................. 14 Running a Data Integration Job (Datamap) ....................................................................................................... 15 Datamap Testing ........................................................................................................................................... 15 Manual Run ................................................................................................................................................... 16 Scheduled Run............................................................................................................................................... 18 Error Handling ................................................................................................................................................... 19 Warnings and Notifications ............................................................................................................................... 23
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 3 of 23
Overview
Apatar is an open source cross-platform data integration tool that can be installed and run on any machine that has some sort of user interface. The tool is designed to enable batch data integration and provide simple user interface so that anyone, not just technical experts, can set up data integrations. Latest public version: http://www.apatar.com/download.html Patches: http://www.apatarforge.org/patches.html Latest source code: http://apatar.svn.sourceforge.net/viewvc/apatar/sourcecode_second/ Apatar Overview Demo: http://apatar.com/demo/Apatar_Overview/Apatar_Overview.html Other Demos: http://apatarforge.org/wiki/display/DEM/Apatar+Web+Demos Forums: http://www.apatarforge.org/forums/ Bug tracker: http://apatarforge.org/bugs/secure/Dashboard.jspa
Programming language: Development platform: Query languages: Temporary database: Supported Operating Systems:
J2EE Eclipse SQL, SOAP/XML Apache Derby Windows, Linux RedHat, SUSE Linux, MacOS
Installation
NOTE: If this is not the first time you install Apatar and you are installing Apatar to the same folder as previously, before you start the installation process, make sure you don’t have any datamaps in the folder you’re installing Apatar to, because the folder will be cleared when installation begins and you will lose your datamaps.
Windows
1) Run the .exe file you have downloaded. 2) At the first screen of the installer you select the components to be installed.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 4 of 23
If you already have Java version 1.6x installed, uncheck ‘Java installer’. If you do not want to see some connectors, data quality services, or operations displayed in the application, open the related list and uncheck the related components. 3) Once you have selected the components you want to have installed, click ‘Next’. 4) At the next screen you get to select the folder that Apatar will be installed to and click ‘Next’. By default, the application is installed to C:\Program Files\Apatar. You can have several instances of Apatar installed and running at the same time if you install them to different directories.
NOTE: If you have Vista or Windows 7, it is recommended that you install Apatar to a folder other than C:\Program Files\. If you face issues when you launch Apatar at these systems, please review the following discussion: http://www.apatarforge.org/forums/viewtopic.php?t=658&highlight=javaw
5) At the last screen you get to select the name under which the application will appear on the list of programs in Start>Programs menu. Again, if you would like to have a number of Apatar instances installed (different versions, for example) make sure each instance is called differently. 6) Once the application is installed, you can launch it by clicking ‘Application’ or ‘Application no Apex’ in Start>Programs>Apatar or ‘Scheduling’ if you want to start Apatar’s scheduling application. Alternatively, you can double click the application.bat, application_noApex.bat, or scheduling.bat in the folder that Apatar is installed to.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 5 of 23
Linux
To install Apatar for Linux, 1) Unpack the "apatar_.tar.gz" archive into any directory (e.g., ). 2) Change system parameters for all files with ".sh" extension in directory For example, Run this command from consol: #chmod 777 application.sh 3) To start using Apatar, run any file that has the ".sh" extension. If you would like to run Apatar as a regular application (default), you need to start up the "application.sh" file. If you would like to run Apatar as a scheduling application (scheduling), you need to start up the "scheduling.sh" file (for example, #./application.sh).
Registration
When you start Apatar for the first time, the registration form opens up.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 6 of 23
If you have previously registered a user with Apatar (via Apatar application or at www.apatarforge.org), keep ‘Existing User’ selection and enter your username and password. If you don’t yet have your username and password, select ‘New User’ and fill in the registration form. You can check whether the username you entered is taken or available before submitting the form by clicking ‘Check Availability’ next to the ‘User Name’ field. While creating your password, keep in mind that you can only use letters and digits. You can always change your user details at your profile page at http://www.apatarforge.org/datamaps/index.php You can also use the username and password created here to submit and track issues in our bug tracking system at http://apatarforge.org/bugs/secure/Dashboard.jspa, and participate in our forum discussions at http://www.apatarforge.org/forums/ If you are using a proxy server, tick the ‘Set up Proxy Server’ checkbox and enter your proxy details.
NOTE: You have to be connected to the Internet during the registration, as Apatar will need to send the data you entered to the server to verify your username and password or create a new user.
Application Components
Once you are done with the registration, you can start working with the application.
Application vs. Application no Apex
There are two applications available after installation: Application and Application no Apex. The only difference between them is that Application no Apex saves Salesforce access credentials. So if you are working with Salesforce, and especially if you are scheduling Salesforce integrations, use Application no Apex.
NOTE: If you open a datamap by double clicking it, it is opened with Application.
If you opened your Salesforce integration datamap in Application, exit Apatar without saving the datamap. This way, your Salesforce access credentials will not be lost.
Top Menu
FILE: New Open Save Save As Publish to Apatar
340 S. LEMON AVE, SUITE #7002
creates a new datamap file opens an existing datamap saves the datamap saves the datamap under a different name/to a different location posts your datamap to www.apatarforge.org if you would like to share it with other Apatar users
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 7 of 23
Scheduling Run Options: Proxy
opens Apatar’s scheduling application starts the transformation
lets you enter/modify your proxy server settings. Details entered here will be applied throughout Apatar application allows you to set the date and time format that is convenient for you. This allowed Apatar to simplify the process of filtering, validating, etc. data by date and/or time. You will not need to know the exact format of date/time, as it's stored in you database. Instead, if there's a need to validate data by date, you will enter the date in the format that is default for your instance of the application.
Date and Time
Detailed Guide: http://www.apatarforge.org/wiki/display/AUG/Date+and+Time+Settings
Debug Options
if checked, debug and error logs will be cleared each time you click ‘File>Run’ or ‘Run and Preview Results’. This way, if errors occur during transformations you can be sure that the logs contain up-to-date information closes Apatar application
Exit
EDIT:
NOTE: Not available in Apatar version 1.12.13 and older
Cut Copy Paste Delete
These menu items let you copy/cut and paste or delete parts of your datamaps within the same datamap file or from one datamap file to another. You can copy configured connectors and/or operations, field mappings and functions. VIEW: Changes the application skin
DEBUG: Show Output (‘Debug Console’ window)
340 S. LEMON AVE, SUITE #7002
shows information on successful and unsuccessful actions performed by the application
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 8 of 23
Show Error (‘Error Console’ window)
shows information related to errors
The same information is written to debug_output.txt and error)output.txt files respectively. (The files are located in the folder that you have Apatar installed to.) If you click ‘Clear’ in Debug Console, debug information will be deleted from this window and debug_output.txt file. If you click ‘Clear’ in Error Console, debug information will be deleted from this window and error_output.txt file. If you have ‘Clear debug and error outputs before each run’ checked in ‘File>Options>Debug Options’, information will be deleted from both consoles and output files each time you click ‘File>Run’ or ‘Run and Preview Results’. COMMUNITY: Catalog of Datamaps Demos Forums Wiki Open the related www.apatarforge.org pages HELP: About Feature Request Submit Bugs Tutorials product information opens a feature request form opens a bug submit form opens the community documentation web page
Context Menu
Configure Cut Copy Paste Delete opens a connector, operation, or function for configuration let you copy/cut and paste or delete parts of your datamaps within the same datamap file or from one datamap file to another. You can copy configured connectors and/or operations, field mappings and functions
Change Name Run and Preview Results
renames a component processes the selected node and previous nodes(connectors and operations); if clicked on a connector or there’s a connector preceding the selected node, the data will be written to the connector(s) and records resulting from this node processing will be shown.
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
340 S. LEMON AVE, SUITE #7002
Apatar Quick Start Guide
Page 9 of 23
List of Nodes
On the left, there’s a tree with nodes grouped by type. Connectors represent data sources that you can access. Data Quality Services are connectors to some CDYNE and StrikeIron’s web services (you must have an account with the related web service to use it) Operations are actions that you can perform with your data.
Work Area
The bigger part of the application window is taken up by the work area where you design your data integrations (datamaps)
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 10 of 23
Supported Data Sources (Connectors)
Having over 30 connectors, Apatar works with the following data source:
Applications Centric CRM Compiere Eloqua EnterpriseDB GoldMine OpenBravo ERP Salesforce SugarCRM vTiger CRM other systems Databases DBase IBM DB2 IBM AS400 MySQL OpenEdge Oracle PostgreSQL SQLServer Sybase SyBASE Vertica Firebird Files .CSV .TXT EditGrid MS Excel XML File Exchange Amazon S3 BuzzSaw File System Flickr FTP WebDav Protocols HTTP Ldap Other Custom Table E-mail ODBC RSS
Applications data can be accessed via a special connector for that system, a relevant database connector, or an ODBC Generic connector if a system provides an ODBC driver.
Detailed Connectors Guides: http://www.apatarforge.org/wiki/display/GUI/Apatar+Connector+Guides
Using Apatar’s connectors, you can insert or update (upsert) data (except for LDAP connector which is readonly). Some connectors also support delete mode and the connector for Salesforce CRM can synchronize data.
Differences between the Modes: http://www.apatarforge.org/wiki/display/INT/Table+Update
Supported Operations
With Apatar you can: transform data from one system to another preserving links between linked tables/objects; aggregate data from multiple sources; perform inner, left, or right join of data from different tables within one source or different data sources; distinct data; validate data using certain conditions and break it down into several streams based on the validation results; filter data that cannot be filtered by a query at the connector level by a condition or a set of conditions; perform bidirectional update of data between JDBC sources or a JDBC source and Salesforce.
Detailed Operations Guides: http://www.apatarforge.org/wiki/display/OPR/Operation+Guides
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 11 of 23
Each operation (except for Distinct) has at least one ‘Inputs’ tab with fields from your data source and Functions’ tab and an ‘Edit Output’ button.
Use ‘Edit Output’ when you have one operation linked to another one to create output fields in that first operation.
If you click ‘Add from Inputs’, Apatar will copy output fields from input fields. If you have two inputs (in Join or Aggregate operation) and they have fields with the same names, Apatar will add the ‘_2’ suffix to the second field name. Alternatively, you can use ‘+’ and ‘-’ buttons to create fields (set field name and select data types)
NOTE: ‘Edit Output’ only creates fields in Apatar’s temporary table. It cannot be used to create a new table in your data target.
Some operations also have an ‘Automap’ button.
It allows you to link input and output fields that are 100% identical (in terms of field properties, such as name, type, size etc.) automatically.
Functions
All operations have a ‘Functions’ tab located either on the right (in Filter and Validate) or on the left of the screen along with input tab(s). It contains a set of functions that you can use to manipulate your data.
Detailed Functions Guides: http://www.apatarforge.org/wiki/display/FUN/Apatar+Function+Guides
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 12 of 23
There are data type conversion functions (like ‘To String’, ‘To Time’, ‘To Date’, etc.) that should be used between field that have different data types. For example, use ‘To String’ function if you are writing from a Date, Boolean, LongText etc field to a Text field; use ‘To Date’ if you write from a text field to a date fields. Constants (Text Constant, Boolean Constant, Current Date Constant, etc.) let you write the same value to a field for all records being processed. Functions like ‘Greater Than’, ‘Contains’, ‘Is Empty’, ‘Match RegExp’, etc. return Boolean ‘true’ or ‘false’ values and can be used to generate a Boolean based on the incoming records field values or to set up conditions in Filter, Validate, or Update operations. Examples of other functions: ‘RegExp’ ‘Concatenate’ ‘Replace With’ ‘And’ and ‘Or’ applies a regular expression to input field values merges two strings into a single one using this function replaces multiple field values with new ones using this function can be used to set up complex conditions
Building a Data Integration Job (Datamap)
Connectors Configuration
Drag and drop connectors to the data sources you need to work with to the work area. To configure a connector either double click it or right click it and select ‘Configure’.
At the first screen, enter your data source access details. Here you can also select the connection to be used or create a new one.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 13 of 23
A connection includes data source access details, table selection, query (where supported), and mode. So if you need to work with different tables within the same data source, it is not recommended to use the same connection as in the connector that’s already working with that data source, because changing connection settings within one connector (selecting a different table or changing a query, for example) will apply these changes to the rest of the connectors using the same connection.
Detailed Connectors Guides: http://www.apatarforge.org/wiki/display/GUI/Apatar+Connector+Guides
For most connectors, the second screen normally contains the list of tables/data objects. The database and Salesforce connectors also have a query box at this screen. This is where you can enter custom queries to filter records before they are retrieved to Apatar’s temporary table, limit the selection of columns, or read data from multiple tables if your data source supports JOIN queries. Select the table you want to work with and click ‘Next’.
NOTE: One connector can only work with one table, unless you are reading from a data source that supports JOIN queries. If you need to write to related tables, use Join operation.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 14 of 23
The next screen shows the list of fields retrieved from the table selected. If you are writing data via a connector, at this screen you also select the mode in which the integration should run and if the table should be cleared if any data is written to it.
If you select Update, Synchronization, or Delete mode, you have to select a field or set of fields that will be used as a primary key to match incoming and existing records.
Operations Configuration
Once you’re done with configuring connectors, drag and drop the right operation(s).
NOTE: If your source and target tables structures are 100% identical (in terms of field number and properties) you can link data sources directly.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 15 of 23
To link connectors and operations click on the output (red) point of your source connector, hold your mouse key, move the cursor to operation’s input (green) point, and release the key. Just like with connectors, double click or left click an operation and select ‘Configure’ to start setting up actual fields mapping or validation/filtering condition. Drag and drop input and output fields and link them in the same way as you linked connectors and operations. Use functions where needed. You can use multiple functions between input and output fields. If you selected update, synchronization, or delete mode, make sure you use the field(s) selected as the primary key in your fields mapping. Keep in mind that you can copy elements of your datamap. Fields mapped can be copied and pasted between operations of the same type (from one Transform to another, but not from Transform to Join, for example) Functions (RegExp, Replace With etc) can be copied from an operation of one type to an operation of another type (from Filter to Validate, for example) You can use ‘Edit’ menu to copy elements of your datamap. Alternatively, once you select the elements to be copied, you can right click them and select the right edit operation. Ctrl+C and Ctrl+V key combinations are enabled.
Running a Data Integration Job (Datamap)
Datamap Testing
Once you have your datamap configured, you can start testing it. To make sure that you see relevant error and debug logs, it is recommended that you either clear logs in Debug> Show Output and Debug Show error before every run/previewing result or tick ‘Clear debug and error logs before each run’ in ‘File>Options>Debug Options’ menu. Start from previewing the results (‘Run and Preview Results’ on the context menu) on your source connector to make sure the right data will be retrieved. If everything is ok, move to the next component. Previewing the results at each step (as opposed to running the entire datamap right away) will help you understand where the problem might be if an error occurs. For example, Let’s say you are retrieving records from SugarCRM, filtering them and writing them to MySQL database.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 16 of 23
Preview on the SugarCRM connector shows the right records, preview on Filter shows you only the records that should be passed further, but preview on Transform does not return anything. This means there’s an issue with fields mapping and you could take a closer look at Transform configuration.
NOTE: Keep in mind that ‘Run and Preview Results’ will write data to a connector.
Manual Run
There are two ways to run a datamap: File>Run on the top application menu Run and Preview Results on the context menu The difference between the two is that ‘File>Run’ will show the Progress window which will then close once a datamap is processed. It is recommended for datamaps that have multiple targets or independent datamaps within one file. Datamaps that are not linked to each other will be processed in the order in which they’ve been created. In the screenshot below datamap 2 was created after datamap 1, so even though it’s located above datamap 1, datamap 2 will be processed only after datamap 1 has been completed (regardless of whether the transformation’s been successful or not)
If you select to run your datamap using ‘Run and Preview Results’, the data will be written to the target connector that you clicked on and, once writing is completed (regardless of the result), the data will be written from this connector.
NOTE: Apatar will retrieve all records from the selected table or matching the Select query entered in the connector, not just the records that have been inserted/updated.
If you have a datamap with multiple targets, you will have to click ‘Run and Preview Results’ at each target to get data written to all of them. Each time the datamap will be processed from the start. This approach is not recommended for datamaps that have autogenerated values (‘ Generate UUID’, ‘CurrentTimeStamp’ and some other functions) written to an intermediate connector.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 17 of 23
Example: Let’s say you are writing to a database that has a table storing company profiles (accounts), a table for contacts, a table where relationships between contacts and accounts, and a separate table with contacts’ e-mail addresses that does have a field holding the related contact id.
As the database doesn’t record ids automatically, ‘GenerateUUID’ function is used in both ‘Transform’ operations to generate ids. The ‘accounts’ and ‘contacts’ connectors are configured to run in the Update mode in case such account or contact already exists in the system. You will first click ‘Run and Preview Results’ on ‘accounts_contacts. This will create an account record in ‘accounts’, a contact record in ‘contacts’, and then a record in ‘accounts_contacts’ that stores ids of contacts and ids of the related accounts. Now when you click ‘Run and Preview Results’ on ‘email_addresses’ without modifying your datamap, the processing will start from both target tables; both ‘Transforms’ will get processed again, new ids will be generated and written to the records that were created during the previous run. When e-mails get written to ‘email_addresses’ they will be related to the right contacts using new ids. However, the account and contact records updated with the new ids will no longer be related because ‘accounts_contacts’ tables hasn’t been updated and it still holds old ids, the ids that no longer exist in the system.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 18 of 23
When your datamap is being processed you see a Progress window:
It shows the steps being completed and the number of records processed. Some types of errors are also shown here. If an error occurs and you would like to stop the transformation, click ‘Cancel’. Make sure ‘Finish’ is shown at the end of the log in the progress window. This will mean that the transformation stopped.
NOTE: During processing, Apatar creates a temporary table where data is stored. So you need to have at least as much space available at the disk where Apatar is installed as the amount of data you are working with.
Scheduled Run
There are two ways to run Apatar datamaps based on a specific schedule: Apatar’s own scheduling application system’s scheduled tasks The scheduling application has the functionality to set up data integrations to run daily or on certain days during a week/ month/year, run once or several times during a day, run until it’s deleted from the list of jobs or stopped or expire after a certain date or number of runs. The specific feature of Apatar’s Scheduling app is that it does not run as a service. If you log off, shut down, or reboot the machine it’s running at, it will close too and your scheduled integrations will not be launched. You will have to open it manually next time you log in. If you use Apatar’s Scheduling application, you can check logs in error_output2.txt and debug_output2.txt files in the folder Apatar’s installed to.
Detailed Guide: http://www.apatarforge.org/wiki/display/ADM/Scheduling
As an alternative to the Scheduling application you can use system’s own scheduled tasks using the command line parameters.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 19 of 23
If you are using Windows Vista or Windows 7, you can enter command line parameters to the scheduled task itself. For Windows XP you will need to create a .bat file (ordinary text file saved with .bat extension) that would contain the correct command to be executed and schedule this .bat file.
Detailed Guide: http://www.apatarforge.org/wiki/display/ADM/How+to+Launch+Apatar+or+DataMap+from+the+Command+Line
When you set up scheduled tasks in the system, remember to enter the username and password of the user under which tasks should be run. If you schedule Apatar datamaps this way, logs will be written to error_output.txt and debug_output.txt files in the folder Apatar’s installed to. As Apatar doesn’t have any native functionality to be triggered by certain events in other systems and applications, these command line parameters can also be used as part of a script that will make Apatar a part of a more complex process and start a datamap processing upon a certain event.
NOTE: One Apatar application can only process one datamap at a time. If you need to have several independent datamaps processed at the same time, please install several instances of Apatar and use a different application to run each datamap.
Error Handling
Here are some typical errors returned by Apatar. They appear either in Progress window or in Debug>Show Error or in both places. ‘ArrayIndexOutOfBoundsException: 0’, ‘StringIndexOutOfBoundsException: String index out of range: -1’ Visual signs of the error: None Problem: Clicks on components that are not clickable Solution: None. These are errors related to UI and not influencing actual data transformations. Should be ignored. ‘Table/View 'TEMP1285164176545' does not exist’ Visual signs of the error: An empty preview screen with no fields.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 20 of 23
There are several reasons for this error. Problem 1: If you are reading from a database using a join query you are probably selecting fields with the same name, RECID for example. In this case, the error will most likely be accompanied by another error like: Column name 'RECID' appears more than once in the CREATE TABLE statement. Solution: If you need both of the fields, select one of them under a different name. Problem 2: While creating a temporary table Derby database malfunctioned and could not build a table. Solution: Go to Apatar folder, delete ‘tempdb’ folder, and start Apatar again. ‘Invalid character string format for type SMALLINT’ and similar errors Visual signs of the error: Window with no or only existing records shown on preview.
Problem: Fields of incompatible types are linked directly. Solution: Insert the proper data type conversion function (To String, To Int16, To Date, etc.) between the input and output fields of different types.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 21 of 23
‘A truncation error was encountered trying to shrink VARCHAR 'sometestvaluehere' to length 2.’ Visual signs of the error: The preview window shows no records (if the error occurred on all records) or just records where this error didn’t occur.
Problem: An input field contained more characters than a related output field allows. Solution: Either change output field size to allow the same number of characters as the input field, or, if this is not possible, use Crop Right function (if applied to fields other than text fields, To String should be used before it) ‘Column 'Company' specified twice’ Visual signs of the error: The preview window shows no records.
Problem: An output field is used twice in fields mapping within the same operation. Solution: Review your fields mapping and make sure each output field is only used once. ‘Comparisons between 'VARCHAR (UCS_BASIC)' and 'LONG VARCHAR (UCS_BASIC)' are not supported.’ Visual signs of the error: The preview window shows no records.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 22 of 23
Problem: ‘Join’ operation uses fields of different types in ‘Join on’ tab to match records from different tables. Solution: If you are working with a database as one of the sources, you can cast the field(s) used in ‘Join on’ to transform it to the same type as the related field of the second data source. Alternatively, use ‘Transform’ between a data source and ‘Join’. In ‘Transform’ use ‘Edit Output’>’Add from Inputs’ to create output fields, find the field you are going to join on and change its data type to the data type of the other data source field you will be relating it to. In the work area, link all the fields you‘re going to be working with. In ‘Join’ go to ‘Join on’ and re-select the field with changed data type so that it’s updated in Apatar’s temporary database. If you also used this field in fields mapping in ‘Join’, make sure to replace it with the new field. Each node processed several times Visual signs of the error: Progress log shows that each connector and operation is processed several times though they are only linked to one other component from their output points.
Problem: Apache Derby database malfunction.
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM
Apatar Quick Start Guide
Page 23 of 23
Solution: Close Apatar, delete ‘temdb’ folder from the folder you have Apatar installed to, start Apatar again.
Warnings and Notifications
‘An error occurred while opening the Datamap: Uninitialized properties were found.‘
Problem: A datamap was created using an older version of Apatar. The newer version of the application, which the datamap is opened in, has some important modifications in one of the connectors or operations used. The modification might not influence the overall datamap performance though. Solution: Click through the connectors and operations to make sure they are configured properly ‘Current DataMap’ date and time settings differ from your default applications configuration.’
Problem: The instance of Apatar, which the datamap was created in, has date and time settings that differ from default date and time settings used in your Apatar application. Solution: Follow the steps mentioned in the warning. If you decided not to change your applications date and time settings, check operation(s) configuration. If there are date or time contacts or date and/or time are used in comparison functions like Greater Than, Equals etc., their format should be the same, as the default date and time format set in Apatar (in File>Options>Date and Time)
340 S. LEMON AVE, SUITE #7002
● WALNUT CA 91789 ● TEL [617] 848-5959 ● FAX [866] 201-3646 ● WWW.APATAR.COM 