Pervasive Integration Agent User Guide

Overview

This page provides you with instructions for the basic configuration and operation of Pervasive Integration Agent.

Contents

This basic configuration consists of the following topics:

Starting and Signing Into Integration Agent

To use sign into Integration Agent, complete the following steps:

  1. Start the application initially from any of the following:
    • a shortcut icon Agent Icon on the desktop.
    • Programs->Pervasive->Integration Agent->Integration Agent in the Start Menu.
    • runAgent.bat in Program Files->Pervasive->IntegrationAgent.
  2. Sign into the Integration Agent using your Pervasive DataCloud User name and password. Click <Sign In>.

Notes: Agent will startup automatically when Windows starts up.

If Integration Agent is running but the interface is not visible, bring up the interface by double-clicking the Agent Icon icon in the System Tray.

The Stay signed in checkbox will enable Agent to automatically log the user back in if a server outage occurs. Agent is designed to startup when the user logs on. Agent will not be able to resume running integration schedules until a user signs in manually to the Agent. Alternately, you can setup Agent to run as a service.

Pervasive Agent Sign In Dialog Box
 

Back to top

Installing Integrations

The licensed integrations from your DataCloud will be displayed in the Integration Agent dialog box. You can install these integrations onto your local machine. If an integration is already installed then you may re-download, reinstall, and update the integration.

To install integrations, complete the following steps:

  1. Click the row for the integration to install and click <Install>.

    Integration Agent Dialog Box
     
  2. Repeat this step as necessary to install additional integrations.

The Install State messages are NOT_INSTALLED, UPDATE_AVAILABLE, DOWNLOADING, INSTALLING, INSTALLED, OFFLINE, UNINSTALLING, and ERROR.

The Run State messages are READY, RUNNING, BLOCKED, and ERROR.

 Notes: The BLOCKED message in the Run State indicates that the integration can only be run on demand. See Running Integrations On Demand. When an integration is running OFFLINE, the logs will not propagate to the provisioning and updates will no occur.

Back to top

Installing .exe files

Some integrations depend on additional software to function properly.  An example is a QuickBooks to Salesforce integration that depends on the QuickBooks SDK being installed. These integration packages may bundle their software dependencies in the form of additional .exe files. 

In our example, the QuickBooks to Salesforce integration may bundle the QuickBooks SDK install .exe file. The installation of the integration package will trigger these any additional .exe files to run.

For security, a dialog box will prompt the the user to allow these additional .exe files to run.

Install exe dialog box

Back to top

Running Integrations

Integration Agent provides three options to run integrations. The options are:

  • Manual- a user can click <Run> to manually run the selected integration.
  • Scheduled- one or more integrations can be scheduled to run at regular intervals. 
  • On Demand- enables third-party applications to run integrations via Integration Agent. See the following section for additional information.

Running Integrations On Demand

Integration Agent can run integrations on demand. Third-party applications can use the DataCloud API to manipulate a parameter called "RunNow" and change that parameter's value to "1".  This will create a signal to the Agent that a run should take place.

Each time Integration Agent runs an integration, Agent first asks the DataCloud for the permission to run integrations by making a call to the DataCloud API.  Agent determines if it executes the integration by reading the state of the "RunNow" parameter in the DataCloud:

  • If the "RunNow" parameter exists and that parameter's value is set to "1", then the integration will take place.
  • If the "RunNow" parameter exists and that parameter's value is not set to "1", then the integration will be blocked and the integration will not take place. If a run is blocked, Integration Agent will display Blocked in the Run State field. After the integration has finished running, the "RunNow" parameter's value will be set to "0".

Note: The majority of integrations will not be setup to run on-demand and therefor will not have a "RunNow" parameter.  These integrations will never be blocked.

If any installed integration will be run on-demand, the Agent should be configured to:

  • frequently ask for permission to execute that integration. In order to configure the Agent to frequently ask for permission to execute an integration, that integration must be scheduled to run at some regular interval.
  • automatically receive updates to the "RunNow" parameter. In order to configure the Agent to automatically receive updates to the "RunNow" parameter in the Change Settings dialog box under the Pre-run update settings heading, enable the Install updates automatically before each integration run checkbox and click <Save Changes>.

    Settings Dialog Box

Tip: A lag time can occur between the third-party application triggering a run in the DataCloud and the integration actually starting to execute. To reduce the lag time, schedule the integration to run more frequently. See Configuring an Integration Schedule.

Back to top

Scheduling Integrations

  1. Click the Integration to modify in the Integration Agent dialog box.

Integration Selection Dialog Box
 

  1. Click the message in Run Schedule field to open the Change Run Schedule dialog box.

Change Run Schedule Dialog Box
 

  1. In the Change Run Schedule dialog box, set the schedule for the integration. The scheduling options are:
  • Always use run schedule from the cloud (schedule in the cloud may change)- runs the default integration schedule from the DataCloud.
    Notes: the schedule from the DataCloud is displayed below this option. This option automatically communicates with the DataCloud on five minute intervals.
  • Run integration at regular intervals- sets the interval to run the integration and the start time for the integration. This option will override the cloud schedule.
    Notes:  Runs can occur as frequently as every second or infrequently as every 30 days (or longer). You may also choose not to schedule a run within this option.
  • Never schedule a run- disables the integration from running on a schedule and will prevent the integration from running from Agent and from the DataCloud.
  1. Click <Save Changes>.
  2. Repeat the procedure to modify additional integrations.

Back to top

Changing Global Integration Settings

  1. Click the Settings icon Settings icon to open the Change Settings dialog box.

Settings icon location


Change Settings Dialog Box

  1. In the Change Settings dialog box, set the desired functionality. You may choose from the following options:
  •  Install updates automatically- checks for updates every five minutes and automatically installs available updates for each integration that is INSTALLED.
  • Check for updates but let me choose whether to download and install them- checks for updates every five minutes. If an update is available, the Install State displays UPDATE_AVAILABLE and then you can manually choose to download and install the update.
  • Never periodically check for updates- disables checking for updates every five minutes. You can still manually install integration updates by clicking the update icon Update Icon in the main window and then clicking on Update Integrations button. 

    Update Integrations button

    If an update becomes available, the Install State displays UPDATE_AVAILABLE and then you can manually choose to install the update.
  • Install integration updates automatically before each integration run check box- checks for updates before each integration is run and automatically installs available updates for that integration.
  1. Click <Save Changes>.

Back to top

Configuring an Integration

Advanced users can access and configure their integrations from the DataCloud Management Console. To configure an integration using the DataCloud Management Console, complete the following steps:

  1. Highlight the integration row you wish to configure.
  2. Click <Configure> in the Integration Agent application to launch the DataCloud Management Console.

    Configure button

Note: this feature may be disabled to prevent access to the DataCloud.

Back to top

Updating Integration Agent and Integration Engine

To install the latest version of Integration Agent click the update icon Update Icon in the main window then click the Update Agent button.

Update Agent button

To install the latest version of Integration Engine click the Update Engine button.

Update Enginebutton

Note: Integration Agent will not allow to update itself or Integration Engine while an integration is running.

Back to top

Exiting Integration Agent

Integration Agent will be minimized to the System Tray when the application window is closed. To exit Integration Agent, right click the icon on the tool bar and select Exit.

Exiting Integration Agent

Back to top

Troubleshooting

Use the following sections to troubleshoot issues with Integration Agent.

General Troubleshooting

Use the following steps for general troubleshooting of the Integration Agent: 

  1. Is Java in your Path?
    1. Test that the path is set up properly by typing java in your command prompt.
  2.  Is the correct version of Java in your path?
    1. The 32-bit Agent of DataIntegrator requires 32-bit Java and the 64-bit version requires the 64-bit Java.
  3. Is your DataCloud license valid?
    1. Review the following file ...\Pervasive\DataSolutions\Deployables\12345\License\myLicense.slc
  4. Run Integration Agent in debug mode.
    1. See Creating a runAgentDebugMode.bat file.
    2. The command prompt should stay open and a rolling log is created. If the command prompt closes instantly, then follow the instructions in steps 1 and 2.
    3. If the integration immediately fails and says there is an error uploading the log, then following the instructions in steps 1, 2, 3.
  5. Run the djar from the command prompt.
    1. type djar -pe -i "..\Pervasive\DataSolutions\Deployables\12345\integrationSpec\cosmos.ini" -l "..\Pervasive\DataSolutions\Deployables\12345\integrationSpec\log.log" "..\Pervasive\DataSolutions\Deployables\12345\integrationSpec\my.djar"
    Note: Each integration downloads a different license and writes a cosmos.ini file to run that integration. So you must specify the .ini file.

Back to top

Install and Run State Errors

If the Install State message is ERROR the following conditions may be the reason:

  • The files meant to be downloaded to facilitate the integration were not found.  This is a design issue and the creator of the integration needs to be engaged through whatever support channel is available.
  • The Agent may not have permissions to write files from the cloud to disk.  This may be corrected by exiting Integration Agent and restarting the Integration Agent with Windows Administrator rights and retrying the Integration Installation.
  • User failed to run one of the .exe files associated with the integration install. See Installing .exe files.

If the Run State message is ERROR the following conditions may be the reason:

  • Most likely the integration finished with errors. Review the log file for this execution in the DataCloud Management Console to further investigate the issues causing the error. The Management Console can be accessed by clicking the Integration Agent's <Configure> button.  See Configuring an Integration.
  • If run logs are not available in the Management Console and Integration Agent is functioning, check to ensure all required paths in the System PATH environment variable are present and resolve properly.
  • Run the run.bat file located in the local integrationSpec folder.  This bat file should reproduce and errors you've encountered without involving the Agent.  At which point you can engage standard Pervasive Data Integrator support techniques to resolve issues.
  • To further debug the issue, follow the instructions below to create a runAgentDebugMode.bat file.

Back to top

Creating a runAgentDebugMode.bat file

For advanced troubleshooting, you can get more information by viewing the command line window while running Integration Agent.

  1. Browse to the IntegrationAgent folder located in the Program Files/Pervasive directory.
  2. Make a new copy of the runAgent.bat file and name the new file runAgentDebugMode.bat.
  3. Edit runAgentDebugMode.bat in a text editor and replace:
       start "Integration Agent" javaw
    with:
       java
  4. Save the file.
  5. Exit Integration Agent and then run the new runAgentDebugMode.bat file.
  6. Reproduce any errors and note the resulting text in the command window.

    Command window
     

Back to top

Command Window Messages

  • com.pervasive.datasolutions.api.service.CloudAPIException: Error downloading the file from S3:
    Meaning:
      This error indicates that a file has failed to download during installation.
    Resolution:
      Contact the integration developer and notify them of this issue.

  • java.rmi.ServerError: Error occurred in server thread; nested exception is:
            java.lang.NoClassDefFoundError: DataJunction/ec/IMacros

    Meaning:
      The agent can't locate the .jar files necessary to run the integration. This message is typically the result of installing Integration Agent in a separate directory from the Pervasive Data Integrator.
    Resolution:
      Reinstall Integration Agent into the same directory as Pervasive Data Integrator.  The Common directory and the IntegrationAgent directory should be located in the same parent directory.

  • Exception in thread "main" java.lang.UnsatisfiedLinkError: no djecjni.dll in java.library.path
    Meaning:
      A .dll in the Pervasive Data Integrator Common can not be found by the Agent.
    Resolution:
      Add the Pervasive Common directory to your system PATH environment variable as instructed in the Installation guide.  Exit and restart the Agent.

  • Info: manifest doesn't exist
    Meaning:
      This is not an error and does not indicate an issue.  This information can be useful to integration developers.

  • Error 30010: Error reading license file / Error reading version/build info
    Meaning:
      The license file associated with your integration cannot be found, is corrupted, does not enable the connectors needed for your installation or has expired.
    Resolution:
      Check to make sure no updates are available by reinstalling the integration.  Failing that, contact support to update the license file.

Back to top