Error handling transformation and job steps


The ARInput, AROutput, and ARX File Input steps throw an exception if they receive an error when executing API calls. This halts the transformation execution.

To implement out-of-the-box support for skipping error rows and continuing execution of the subsequent input rows, you must define an error handling step in the Spoon client for the related ARInput, AROutput or ARX File Input steps in a transformation. The error handling step could be a text file Output step that writes the error information to an error log file.


Error handling enabled for AROutput step

221_error_handling.jpg

java.lang.OutOfMemoryError: Java heap space

A java.lang.OutOfMemoryError: Java heap space error may occur if multiple concurrent jobs run on an Atrium Integrator server. To resolve this error, increase the Java heap space of Atrium Integrator server process in the armonitor.cfg file.

Directory structure

When designing a file input step (such as ARX File Input or text file input) in a transformation, enter the appropriate UNIX or Windows path available from the AR System server in the Filename field.

Example

Windows directory structure
D:\ARSFolder\subfolder\file.txt

UNIX directory structure
/ARSFolder/subfolder/file.txt

Filename field in the File tab

221_directory_path.png

New Excel columns

If you add a new column to an Excel input file, add it at the end of the worksheet. If you add a new column elsewhere in the worksheet, you must manually add its corresponding field number to the Field tab in the Excel Input step. In addition, you must add all columns from the Excel spreadsheet.

The following error message displays if you use the Excel Input step, sort on any tab in the Fields tab, save the transformation, and then preview rows in the file or run the transformation in AR System or with the Spoon client.

Log Files

Atrium Integrator adapter log files in Windows systems reside in < AR_system_installation_directory >/ARserver/db. Unix log files reside in < AR_system_installation_directory >/db. Carte server log files include:

  • arcarte.log—All Execution Instance messages are recorded in this file according to the logging level specified when you created the Execution Instance.
  • arcarte-stdout-timestamp.log—All messages that the Carte server prints to the console are recorded in this file.
  • arcarte-stderr-timestamp.log—All error messages that the Carte server prints to the console are recorded in this file.

The ARDBC plug-in log file is arjavaplugin.log. All ARDBC plug-in messages are recorded in this file. By default the log level is warn. If you want to log info or debug messages:

  1. Open < AR_system_installation_directory >/pluginsvr/log4j_pluginsvr.xml
  2. Search for logger com.bmc.arsys.pdi.
  3. Change the log level to info or debug.
  4. Restart the AR System server.
Example

<logger name="com.bmc.arsys.pdi">
<level value="info" />
</logger>

AR System form log files

The Log field in the UDM:ExecutionStatus form shows the log file for a specific Execution Instance. However, the log lines displayed are stored in the Carte server's memory, which has a maximum buffer of 5000 lines to control memory usage. As new log file lines are added, the Carte server deletes the older log file lines. However, this information is retained in the arcarte.log with all other Carte server log file information. See the third-party documentation for more information about this logging limitation.

To configure the Carte server to store more than 5000 log lines, set the KETTLE_MAX_LOG_SIZE_IN_LINES parameter in the armonitor.cfg file for the Carte Java process, and restart the AR System server.

A transformation or job can be configured to log the execution information to AR System logging forms. Use these forms to configure logging:

  • UDM:TransformationLog—Stores transformation instance log.
  • UDM:JobLog—Stores job instance log.
  • UDM:JobEntryLog—Stores job entries log for a specific job instance.
  • UDM:StepLog—Stores steps log for a specific transformation instance.

To enable form-level logging for a transformation or job:

  1. Open the transformation or job in the Spoon client.
  2. Right-click on the transformation or job name.
  3. Click the Logging tab.
  4. Add the AR System server connection and the corresponding AR form name for the log table name. For example, use UDM:TransformationLog for the transformation and UDM:StepLog for the step.
  5. Save the transformation or job.

Spoon client log files

When you run a transformation or job in the Spoon client, the log information is displayed in the Logging tab of the Execution results panel.

Spoon client log information

log_spoon.png

Error message descriptions

This section describes runtime, design, and plug-in error messages for the Atrium Integrator adapter. For related AR System error messages, see AR-System-error-messages.

Runtime error messages

Message

Description

You need to specify a AR System connection.

A connection to AR system is missing from a transformation step.


Open the transformation from the Spoon client. Configure a new or existing AR System connection for the ARInput or AROutput step by using the New and Edit buttons on the General tab. Save and re-run the transformation.

Error Connecting to ARSystem.

An ARInput or AROutput step in your transformation cannot connect to AR System.

Ensure that 1) the AR System server is running when you run the transformation, 2) the connection parameters are specified correctly, and 3) the correct variable values are specified correctly for the AR System connection.

Error parsing the qualification

The ARInput step failed to parse the specified qualification.

Error while fetching status field enum values

The ARInput step failed to fetch the string enum values for the Status field (AR Core field ID 7).

Error while fetching next set of records

The ARInput step failed to fetch the next chunk of records from the AR System server.

Error while converting AR value to Pentaho value

The ARInput step failed to convert the AR System data type value to an  Atrium Integrator value.

Ensure that the source and target data types are compatible.

Error while fetching status history

The ARInput step failed to fetch the Status History field value for a row.

Error while fetching attachment for field: {0}

The ARInput step failed to fetch the Attachment value for a row.

Field {0} couldn't be found on form {1}

The AROutput step cannot find an AR System field contained in the field mapping.


Check the mapping to ensure that the field names are used correctly. To avoid this error, use the mapping editor provided in the AROutput step. To access the editor, press the Edit Mapping button on Field Mapping tab of the AROutput step dialog to access the editor.

Field {0} couldn't be found in the input stream!

The AROutput step cannot locate the stream field (fields from previous steps) and defined in the field mapping.


Check if the hop between the previous step and the AROutput step is disabled. If it is disabled, enable the hop and save the transformation. Also check if a field was removed from a previous step but not removed from the AROutput step field mapping. If it was removed, remove it from the field mapping and save the transformation. In addition, check if the field is defined as an error handling parameter in a previous step. If the hop between the previous step and the AROutput step is not defined as a normal hop or as an error hop, change the hop type from a normal hop to an error hop. Save the transformation.

Error in AROutput Step

The AROutput step failed to send the output to AR System.

Error in BULK ENTRY Transaction: {0}

The AROutput step failed to commit the bulk entry transaction.

More than one entry matched the qualification and the multi match option is set to ERROR

Review the qualification and modify it to ensure that it matches one entry, or change the multi-match option to update first or update all.

Error while parsing matching qualification

The AROutput step failed to parse the specified matching qualification.

No or Empty Currency Code for Currency value for field {0}

The AROutput step cannot find the currency code for the currency field value.


Map the currency code (<currency field name>.TYPE) in the field mapping, or ensure that the stream field (mapped to the currency field) defines the currency code value.

No conversion date for Currency value for field {0}

The AROutput step cannot find the conversion date for the currency field value.


Map the conversion date (<currency field name>.DATE) in the field mapping, or ensure that the stream field (mapped to the currency field) defines the conversion date value.

No Currency value for field {0}

The AROutput step cannot find the decimal value for the currency field.


Map the decimal value (<currency field name>.VALUE) in the field mapping, or ensure that the stream field (mapped to the currency field) defines the decimal value.

No Currency Conversion Ratio Defined from {0} to {1}

A currency conversion between two different currency types was needed during the execution of a transformation that included the AROutput step. The conversion ratio was not defined in the AR System Currency Ratios form.


Supply conversion ratios in the AR System Currency Ratios form for all possible conversions.

Error while fetching fields information for form {0}

The AROutput step failed to fetch field information from a form in AR System.

EXTERNAL operator is not supported in the matching qualification

Remove the External operator from the qualification.

No such form field having field ID {0}

The AROutput step cannot find the Field ID used in the matching qualification on the form.


Review the qualification and remove the non-existent Field ID references. Use the Spoon client to access the Qualification editor provided in the AROutput step dialog, and configure the qualification. To access the qualification editor, press the Configure Matching Qualification button on the Duplicates tab.

Wrong Matching Qualification. Stream field {0} should be used on the right hand side of a relational operation.

The AROutput step determined that stream fields (fields from previous steps) are used in the left side of the relation operation in the matching qualification.


Modify the matching qualification to use stream fields on the right side of the relation operation in the matching qualification. Use the Spoon client to access the qualification editor provided in the AROutput step dialog, and configure the qualification. Press the Configure Matching Qualification button on the Duplicates tab to access the qualification editor.

No such stream field [{0}]

The AROutput step cannot find a stream field (field from the previous step) referenced in a matching qualification.


Review the qualification to remove the non-existing stream field references. Use the Spoon client to access the qualification editor provided in the AROutput step dialog, and configure the qualification. Press the Configure Matching Qualification button on the Duplicates tab to access the qualification editor.

Error initializing step...java.io.FileNotFoundException:

The file path specified in the ARX File Input step or specified as a variable value is not found on the system.


Ensure that the file is present on the system.

Error while setting the private RPC Queue

An error occurred while setting the private RPC queue number on the AR connection.

Error while reloading the password collection

An error occurred while reloading information from the UDM:RAppPassword form.

Did not find BMC Helix ITSM Application Service password for server {0} in UDM:RAppPassword Form on server {1}

The BMC Helix ITSM Application Service password for a server is missing from the UDM:RAppPassword form.


Add an entry for the server in this form.

Error while impersonating user {0}

An error occurred while impersonating the provided user.

Error occurred while trying to create transaction on the ARdatabase

An error occurred while starting a client managed transaction on the AR connection.

No valid database connection defined!

No connection related information is defined on AR connection. Please define host, port, TCP port, RPC port, user name on connection to avoid this error.

Error occurred while trying to connect to the database

An error occurred while connecting to AR System.

Error disconnecting ARdatabase: {0}

An error occurred while disconnecting from AR System.

Error performing commit on connection

An error occurred while committing the client managed transaction on the AR connection.

Error performing rollback on connection

An error occurred while rolling back the client managed transaction on the AR connection.

Error occurred while trying to get list of tables

An error occurred while fetching a list of form names from AR System.

Error occurred while trying to get table fields

An error occurred while fetching a list of fields on a form from AR System. 

Error occurred while trying to get table entries

An error occurred while fetching form entries from AR System.

Error while converting AR value to pentaho value

An error occurred while converting an AR data type value to an Atrium Integrator value.

Ensure that the source and target data types are compatible.

Error while fetching last log date

An error occurred while fetching the last log date from log forms such as, the UDM:TransformationLog form or the UDM:JobLog form.

Unable to write log record to log form {0}

An error occurred while writing a log record to the logging form, such as the UDM:TransformationLog form or the UDM:JobLog form.

Error while fetching log records from {0} form

An error occurred while fetching log records from logging form such as, the UDM:TransformationLog form or the UDM:JobLog form.

Error while clearing log form entries from {0} form

An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog form or the UDM:JobLog form. 

A log timeout was defined for log table {0}, but it doesn't have a log field

A log timeout value is defined in the logging setting, but the log date field is not defined on the log form.


Ensure that you are using out-of-the box logging forms such as, the UDM:TransformationLog form or the UDM:JobLog form. If you want to use your own logging form, ensure that you add all fields with the same IDs that are used in the out-of-the-box logging forms.

Unable to clean up old log records from log table {0}

An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog form or the UDM:JobLog form. 

Invalid selection value {0} for field [Name - {1}, ID - {2}]

The AROutput step found that the provided string value is not a valid string alias selection value for the enum field.
Check the definition of the field on the AR System form to get the valid string alias values for that enum field, and use a valid value.

Exception while converting string to diary list value1

The AROutput step cannot convert a string value to a diary list field value. 

Java.lang.OutofMemoryError

If this error message appears in transformation and/or job execution logs or in the arcarte.log file, the Carte server does not have sufficient memory to execute jobs. This error may result when more than two jobs are running concurrently on a Carte server. Increase the heap size of the Java Carte process in the armonitor.cfg file, and restart AR System.

Design-time error messages

Message

Description

Please select a valid connection!

The AR System connection is not configured for an ARInput or AROutput step.


Configure a new connection, or select existing connections for an ARInput or AROutput step using the New and Edit buttons on the General tab of the ARInput or AROutput step dialog.

Please select a form name to use

The Form name is not configured for the ARInput or AROutput step.


Configure the form name for the ARInput or AROutput step by using the Browse button on the General tab of the step dialog.

No fields are specified. Please add fields in fields tab.

Configure fields in the ARInput step.


Use the Get Fields button on the Fields tab in the ARInput step dialog to see all the form fields from the .arx file. Delete or add fields as needed.

Field with name {0} does not exist on form {1}

A Field name specified on Fields tab was not found on the ARInput step form.


Make sure you entered the correct Field name on the Fields tab. Use the Get Fields button on the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.

Invalid field ID {0}. Field ID should be a number.

A Field ID specified on Fields tab is non-numeric for the ARInput step.


Ensure that the correct Field ID was entered on the Fields tab. To avoid this error, use the Get Fields button on the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.

Field with ID {0} does not exist on form {1}

A Field ID specified on Fields tab is not found on the ARInput step form.


Ensure that you entered the correct Field ID in the Fields tab in the ARInput step dialog. Use the Get Fields button on the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.

Field with ID {0} does not have name {1} on form {2}

The Field Name for a Field ID is different than the actual Field name of the Field ID in the form definition.

Ensure that you entered the correct Field Name in the Fields tab in the ARInput step dialog. It must be in sync with the form definition fields in your AR System server. Use the Get Fields button on the Fields tab in the ARInput step dialog to see all the fields on a form. Delete or add fields as needed.

No field mappings are specified. Please specify field mappings in field mapping tab.

Field mappings are not configured for the AROutput step.


Configure the field mappings with the AROutput step field mapping editor. To access the editor, press the Edit Mapping button on Field Mapping tab of AR output step dialog.

It was not possible to retrieve the source fields for this step because of an error: {0}

The AROutput step dialog cannot retrieve any stream fields (fields from previous steps).


If the AROutput step is not connected to a previous step, create a hop between the previous step and the AROutput step.

It was not possible to retrieve the target fields for this step because of an error: {0}

The AROutput step dialog could not fetch AR fields from a form. Problems establishing a connection to the AR System server might exist.

Certain referenced fields were not found! These source fields were not found: {0}

The AROutput step dialog cannot find some stream fields (fields from previous steps) used in field mappings.


Check if the hop between the previous step and the AROutput step is disabled. If it is disabled, enable the hop and save the transformation. Also check if a field was removed from previous step but not removed from the AROutput step field mapping. If it was removed, remove it from the field mapping and save the transformation. In addition, check if the field is defined as an error handling parameter in a previous step. If the hop between the previous step and the AROutput step is not defined as a normal hop or as an error hop, change the hop type from a normal hop to an error hop. Save the transformation.

Certain referenced fields were not found! These target fields were not found: {0}

The AROutput step dialog cannot find AR System fields specified in the field mapping. Check the mapping to ensure that the correct field names are used.

An ARX file is not specified. You must specify the correct ARX file.

The ARX file path is not configured for the ARX File Input step.


In the Spoon client, add the ARX file path using the Browse button on the ARX File Input step dialog, or specify the value as a variable and supply the variable value at execution time.

No schema name is specified, please specify schema name.

The Form name is not configured in the ARX File Input step.


In the Spoon client, open the combo box for the ARX File Input step and enter the Form name.

Chunk size cannot be blank, please specify chunk size.

Use a Chunk size value greater than zero in the ARX File Input step.

No fields are specified. Please add fields in fields tab.

You must configure fields in the ARInput step.


Use the Get Fields button on the Fields tab in the ARInput step dialog to see all form fields from the .arx file. Delete or add fields as needed.

Plug-in error messages

Message

Description

Error in initializing the plug-in

The ARDBC plug-in failed to initialize.

Error fetching in progress import requests

The ARDBC plug-in failed to fetch the requests left to process since the last processing.

Carte Server Name is not populated in UDM:Config for entry ID {0}

In a server group environment, the Atrium Integrator Engine Server Name field is not populated with an Entry ID from the UDM:Config form.

Enter a value in the Entry ID field, and enter the co-located AR System server name (Server-Connect-Name) in the Atrium Integrator Engine Server Name field. Using the value in this field, the Atrium Integrator adpater ARDBC plug-in will send the Carte server the request.

Did not find BMC Helix ITSM Application Service password for server {0} in UDM:RAppPassword Form on server {1}

A AR System server BMC Helix ITSM Application Service password is missing from the UDM:RAppPassword form.

Add an entry for the AR System server in this form.

Create Entry not supported on form {0}

The Atrium Integrator adapter ARDBC plug-in only supports the Create Entry call in the UDM:Import form, the UDM:Execution form, and the UDM:ScheduleProcessor form.

Error while creating an entry on form {0}

A Create Entry operation failed in an Atrium Integrator adapter ARDBC plug-in vendor form.

There was an error removing the execution instance {0} of transformation/job {1}on the Carte server {2}: {message}

The Atrium Integrator adapter ARDBC plug-in failed to remove an Execution Instance of a transformation or job from the Carte server.


Review the Carte server error message and the arcarte.log file for more information about this error.

There was an error doing pause/resume for execution instance {0} of transformation/job {1} on the Carte server {2}: {message}

The Atrium Integrator adapter ARDBC plug-in failed to pause or resume an Execution Instance of a transformation from the Carte server.

Review the Carte server error message and the arcarte.log file for more information about this error.

There was an error stopping the execution instance {0} of transformation/job {1} on the Carte server {2}: {message}

The Atrium Integrator adapter ARDBC plug-in failed to stop an Execution Instance of a transformation or job from the Carte server.

Review the Carte server error message and the arcarte.log file for more information about this error.

There was an error starting the execution instance {0} of transformation/job {1} on the Carte server {1}: {message}

The Atrium Integrator adapter ARDBC plug-in failed to start an Execution Instance of a transformation or job from the Carte server.

Review the Carte server error message and the arcarte.log file for more information about this error.

Repository Directory or Object ID is required for Operation CREATE_EXEC_INSTANCE

For the Create Execution Instance request, you must provide a Repository Directory or an Object ID for the transformation or job.

There was an error posting the transformation/job on the Carte server {0}: {message}

The Atrium Integrator adapter ARDBC plug-in failed to create an Execution Instance of a transformation or job on the Carte server.


Review the Carte server error message and the arcarte.log file for more information about this error.

Failed to reload password collection

The Atrium Integrator adapter ARDBC plug-in failed to re-read all the passwords from UDM:RAppPassword form.

Get List Entry With Fields not supported on form {0}

The Atrium Integrator adapter ARDBC plug-in only supports a Search entry with a Get List Entry With Fields API call only on the UDM:RepositoryObject form, UDM:ExecutionStatus form, and the UDM:StepStatus form.

Error while fetching data from form

A Search Entry operation failed on a vendor form that belongs to the Atrium Integrator adapter ARDBC plug-in.

Qualifier operator OR and NOT are not supported only AND is supported

In the vendor forms that support Search, modify your qualification because only the AND conditional operator (and not OR or NOT) is supported.

Only EQUAL relational operation is supported for qualifier

In the vendor forms that support Search, modify your qualification because only the EQUAL relational operator is supported.

Field {0} is not supported for query. Supported fields for query are {1}

In the vendor forms that support Search, check the associated Field IDs and modify your qualification because an unsupported field is used in the qualification.

No such repository directory {0}

The existing directory name is not valid for the Execution Instance operation on the UDM:Execution form or the Search operation on the UDM:RepositoryObject form.


Provide the correct repository directory name on the UDM:Execution form or the UDM:RepositoryObject form.

Delete Entry not supported on form {0}

Delete Entry API call is not supported on any vendor form that belongs to the Atrium Integrator adapter ARDBC plug-in.

Get Entry not supported on form {0}

Get Entry API call is not supported on this vendor form. The Atrium Integrator adapter ARDBC plug-in only supports Get Entry calls on the UDM:RepositoryObject form, UDM:ExecutionStatus form, and UDM:StepStatus form.

Error while fetching entry from form {0}

A Search Entry operation fails on a vendor form that belongs to the Atrium Integrator adapter ARDBC plug-in.

No Carte server with name {0} exists in UDM:Config form.

A transformation or job uses the UDM:PermissionInfo form, which specifies a Carte server name, but the UDM:Config form does not contain an entry for that Carte server name. Use the correct Carte server name and use the menu in the Atrium Integrator Engine Server Name field on the UDM:PermissionInfo form.

Execution instance name {0} is not unique for transformation/job {1}

The Execution Instance name provided for the Create Execution Instance operation is not unique.


Provide a unique Execution Instance name.

Invalid Execution Instance. Execution Instance {0} does not exist or user {1}is not allowed to access it.

The Execution Instance name provided for the Start, Stop, Pause, Resume or Remove operation does not exist in the database.


Provide the correct existing Execution Instance name for the Start, Stop, Pause, Resume or Remove operation. If the Execution Instance exists, then the current user does not have permission for the Execution Instance record. To add permissions, update Field 112 in the Execution Instance record.

Either a transformation or a job {0} (Object ID {1}, Directory ID {2}) does not exist Or User {2} is not allowed to access transformation/job {3}

The transformation or job provided for the Create Execution Instance operation does not exist.


Provide the correct transformation or job name and directory or object ID. If the transformation or job exists, then the user does not have permission for the transformation or job. To add permissions, update Field 112 in the transformation or the job's record on the UDM:PermissionInfo form.

Missing required parm {0}

The schedule for the transformation or job requires a parameter.


Update the schedule with the required parameter.

{0} should be an integer value.

The schedule for the transformation or job required an integer value.


Update the schedule with a valid integer value.

Error performing asynch task {0}

The ARDBC plug-in failed to process an asynchronous UDM:Import task.

Error processing UDM Import (Entry ID {0})

The ARDBC plug-in failed to process an asynchronous UDM:Import task.

Invalid xml file. Root Element should be transformation or job

The transformation or job definition file attached to the UDM:Import record is not a valid file.

Attach a valid transformation definition (.ktr) or job definition (.kjb) file to the UDM:Import form.

Transformation/Job {0} already exists in repository directory {1}

The transformation or job being imported exists in a repository directory.


Use Overwrite mode to overwrite the existing definition.

No Pentaho repository and Carte server details are present in UDM:Config

The UDM:Config form is empty.


Add repository and Carte server connection information to the form so the Atrium Integrator adapter ARDBC plug-in can process the transformation.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*