Frequently Asked Questions: About  Secure Agent Migration for ICRT Customers

Version 7

    1. What are the benefits of the new agent architecture being introduced in the Spring ’17 Release?


    A new architecture version of the Informatica Cloud Secure agent is being released a part of the Spring ’17 Release. Informatica Cloud customers will gain benefits from the Informatica Cloud Secure Agent version 30 (and later) given the resiliency it offers such as the ability to avoid restarts following the distribution of new connectors and Informatica Cloud upgrades.


    2. What’s new within in for the Informatica Cloud Real Time for the Spring’17?


    Cloud Application Integration customers also gain the following benefits by using Secure Agent version 30.0 (and later):

    Change of Underlying database from H2 to PostgreSQL. The underlying database for Secure Agent version 30.0 and later is now PostgreSQL. For Secure Agents earlier than version 30.0, the underlying database is H2. The PostgreSQL database handles large amounts of data better than the H2 database.

    HTTPS Listener Support. You can now invoke processes published to a Secure Agent using HTTPS/REST or HTTPS/SOAP from on-premises clients.

    Informatica will automatically upgrade all Cloud Application customers who run Secure Agent version 30 and earlier to Secure Agent version 33 in mid-April 2017.


    3. How can I find the version of my Secure Agent?


    1. Login to the Informatica Cloud Service console at
    2. Navigate to Configure > Runtime Environments
    3. Click on the secure agent hyperlink. Verify the version of the agent. If it is less than 30.0, this means that you are in the legacy version of the agent (v26). If you’re in a version greater 30, but 32.2, you are using the latest version of the secure agent in your environment and will be upgraded to v33 on the day of the upgrade (Apr 15 or April 22 2017) depending on which POD your org is located at.


    Note: To find out if your org belongs to APP, APP2, or APP3, login to ICS and look up the URL for the server it redirects.


    Image 1291.png


    4. It appears that my agent version is earlier than version 30, should I upgrade?


    Although you do not need to, you should consider an early upgrade. We suggest that the ICRT service customers do so. By performing an early upgrade to the Secure Agent version 33 you benefit by:

    • sizing and configuring your agent according to your needs
    • validating the upgrade and address issues, if any, prior to the Cloud Spring ’17 release.


    If you’re using agents under Linux using a root account, or are running multiple agents on your Linux server, you must either stop using the root account or perform an early migration to the agents v33. Customers running multiple agents on Linux must also act. 


    5. When should I upgrade?


    You can manually upgrade any time before 22 April if you are hosted on APP2 and APP3.

    First, you need to install the latest Secure Agent. We then need to enable additional packages for you. We ask that you coordinate your installation with the Support Engineer assigned to assist you so that we can enable this package for you. To install the latest Secure Agent and perform your migration follow the steps of the “Early Migration to v33.pdf” document.


    Remember to let us know before you proceed the upgrade so that we can enable additional packages for you.


    6. How do I perform an early upgrade of my Secure Agent?


    Please refer to the guide here at The very first step will be to request Informatica Support to enable additional packages to your existing Process Server license. Please let us know when you are ready to install your Secure Agent so that we can enable these packages for you after you do.


    7. What happens if I don’t upgrade?


    That’s OK. We will auto-upgrade you on Apr 15 (for APP) or Apr 22 (APP 2 or APP 3).  What you won’t get the opportunity to do is to verify the upgrade until after 22 April. Upgrading early gives you this opportunity and ensure that Java Virtual Machine parameters are adequate for your needs.


    8. My agent version is already 30+, should I still upgrade?


    You do not need to. We will auto-upgrade your agent to version V33 on Apr 15 or Apr 22.


    9. How much time should I plan if I perform an early upgrade?


    The upgrade involves the following steps.  on a very high level:

    1. Download and install the new version of the secure agent.
    2. Informatica needs to enable additional packages for you. The packages can be enabled within 15 -30 mins of engaging the Support team. If you let us know in advanced we will arrange to do this in conjunction with your update
    3. Migrating data from the H2 to Postgres. H2 is the built-in database that Process Server used prior to this release. It is being replaced by a Postgres database. The database holds process-related metadata for they payloads that run on your Secure Agent, the Process Server configuration, and runtime data (if the Trace level is not set to None on any of your processes). To maintain your configuration, you will need to migrate your data and metadata. Please see Faq#22 for additional information for H2 database migration to Postgres. If you do not need to maintain your configuration, you can skip this step and simply “republish” connections and processes you’ve deployed to your agent.


      We’ll be happy to discuss these options. Please reach out to us to do so.


    10. I am running my agent on Linux using a “root” account? Will this work?


    If you are running using a Linux root account you must act. You cannot run Process Server under a root account because the Postgres database will not start. You would need to start and run the agent as a non-root user with the new version of the Agent. Running any server using a root account is generally highly discouraged from a security perspective.

    Here are the steps to stop using a Secure Agent using the root account:

    1. If the agent is already running, logged in as root
    2. Stop the agent
    3. Change directory to the agent’s installation directory
    4. Change ownership of the files using “chown -Rf {user}:{group} ./*” from the installation directory from where the agent is installed. e.g.: /home/uashok and on directory listing the infaagent home directory must be listed.
    5. Logout as root
    6. Login as a non-root user (e.g.:uashok)
    7. Start the agent using the non-root user


    11. Are there any important configuration changes that I should be aware when comparing to the previous version?


    When Secure Agent v33 is installed or upgraded, the default settings of the Process Server service will be used. This may be different than what you are using. It is important that you ensure that the configuration you used prior to the upgrade is reapplied after you upgrade or after the automated upgrade. Please make sure that any custom certs that you used in the legacy version of the agent are imported into the new secure agent {Secure Agent V26 Home}\apps\process-engine\conf\ae.cacerts.


    12. Running Windows and have installed the Secure Agent within “Program files”?


    If so, please make sure that Windows User Account Control is disabled. Otherwise reinstall the Secure Agent outside of “Program Files”.


    13. I have installed 3rd party libraries. Do I need to do anything?


    If you are planning to manual early upgrade, you would need to copy the third party libraries used for by the Process Server service from the previous version of the agent {Secure Agent V26 Home}\data\process-engine-custom-lib) to the { Secure Agent 30+ Home}\apps\process-server\ext directory.


    14. I have started my upgrade, and found that the Agent Console Manager keeps reporting that “Not all services are up and running”. What should I look for?


    • Check the status in the ICS console. Please refer to question #3.
    • Check the agentcore.log to start with. Location: {Secure Agent V4 Home}\apps\agentcore and check if there are any errors/exceptions.


    15. Data integration Server service is up and running but the Process Server service is still not up yet. what does this mean?


    Please verify the agent audit logs or the agent core logs. Then, search our Knowledge Base for the error. If you do not find relevant information, then when opening up a case please provide the following information.

    • Your OrgID
    • The secure agent name.
    • Agent core logs: {Secure Agent V4 Home}\apps\agentcore\agentcore.log
    • Process Server Logs: A .zip of the logs directory under {Secure Agent V4 Home}\apps\process-engine


    16. I see some errors similar to the following snippet in the agent core log. What do they mean?


    "ERROR: [agentAuditLogger] - [LCM_10004] process-engine-xxxx.x encountered an error during deployment". Please refer to:


    17. How can I confirm that my agent is upgraded and all is well?


    Refer to runtime environments. If you’re manually upgrading your agent prior to the Spring ’17 upgrade, your agent should show v32.2 as in the screenshot in question #3. After the upgrade, the agent’s version will be 33. The Process Server and the Data Integration Server services will report as “up and running”. Also, please verify that the agent core logs does not show any recent error codes. And, confirm that the following statements appear in the log

    The service [Data_Integration_Server_26.0.11] state has changed to [RUNNING]

    The service [process-engine_1058.2] state has changed to [RUNNING]


    Note: The version information can differ.


    18. Can I restart the Process Server service?


    Services cannot currently be restarted individually. We suggest that you restart your secure agent for any changes you make to the process server configuration.


    19. What does the version mean? How do I know that I am on the latest version of the process server?


    This is interpreted as the major version.minor version. When you early upgrade, the Process Server version will show up as 1058.XX. This indicates that you are on the latest version. The major version of the Process Server will be upgraded during the monthly Agent upgrades, scheduled every second Saturday of the month. This is subject to change. But prior to the upgrade, we will send out email notifications to the Org users, or a best practice you can subscribe to the calendar here to receive any updates on the upgrade dates.


    20. Will the version number change? What constitutes to the change?


    Yes the major version will change during monthly upgrades. For example, after the Spring’17 release, the process server will show up greater than  >1058. The minor version will change for any configuration changes you perform on the Runtime Environment configuration changes you perform for the Process Server in the ICS console. Any changes will immediately upgrade the next minor version, like shown in the screenshot below and will not take effect until you restart the secure agent. For example:


    Existing version:

    Image 1295.png

    When I change the memory parameter under Runtime environment > system configuration detail > process server > JVM max-heap, and click on Done, I’ll immediately see:

    Image 1296.png

    The new version 1058.2 will not be effective unless the secure agent is restarted. Upon server restart, you will find the new version as Up and Running.


    21. Are there any disk space availability requirements for the upgrade?


    Yes, we suggest the following:

    2* ("Main" directory size) + 2 GB + (2.5)*H2 database size {You can find the size of the H2 database file at {Secure Agent V3 Home}\data\process-engine-db\ProcessEngine.h2.db


    22. My H2 database shows up as being very large in size. Do we need to perform any other configuration changes to speed up the migration?


    If the size of your H2 database exceeds 20GB the conversion of the database data from H2 to Postgres will take more time than desired using the 2GB of JVM heap we allocate by default. To reduce the data migration time, if the number of unpurged processes is as high as 1 million, we recommend that you set a system-level PE_MIGRATION_MEMORY environmental variable.


    Unless you need to maintain completed processes for the migration you might consider manually purging these using your agent’s Process Console. Navigate to Admin > Maintenance > Storage. On the Manual tab select the “Completed / Faulted before” setting to do so.


    Set an upper limit for the PE_MIGRATION_MEMORY system-wide environment variable based on your available memory. Use System Properties for Microsoft Windows or the shell in Linux to do so.


    Linux example using 6GB:


    setenv PE_MIGRATION_MEMORY "-Xms1024m -Xmx6144m"


    23. Has your process server come up as "Up and Running" after the Spring’17 upgrade? If not, if it is in the Error state, here are some commonly identified errors with the Process Server (ICRT) agent package upgrade in Spring ’17. These errors would be in the agent core logs or the process server related scripts logs


    • Agent core logs: {Agent_Home}\apps\agentcore\agentcore.log
    • Scripts Logs: {Agent_Home}\apps\process-engine\logs\scripts.log


    ERROR [com.activee.rt.hub.agent.util.AeWindowsAgentPreCheckManager] - java.lang.Exception: There is a different PostgreSQL instance already running.

    This indicates that there is a different postgresql instance running in the same port as what secure agent is attempting to start its embedded instance of postgresql at the port 5432.You could change the PostgeSQl port that the Process Server is attempting to connect to during the startup.


    Refer KB: 511662

    java.lang.Exception: Shutdown port 7005 is either misconfigured or already in use.

    This indicates one of the port - http, https or the shutdown port (as in this error) is not available for the process server to start up.

    Refer KB: 511663

    Error delivering request targeted for URI: nullactive-bpel/AeAgentProcessInvokeServlet/{Org_ID}/ICSExecuteTask, with a caused by reason:

    java.lang.IllegalArgumentException: host parameter is null

    Occurs when the process in the agent, attempts to invoke the ics task, even after the Process Server show as up and running.

    Refer KB: 511832

    [com.activee.rt.hub.agent.util.AeAbstractAgentPreCheckManager] - java.lang.Exception: Agent process is started by user with root privileges.

    You cannot run Process Server under a root account because the Postgres database will not start.

    Refer KB:  511859

    Postgre Server failed to start - waiting for server to start....The current directory is invalid.

    Agent perhaps running as the local domain user. the suggestion is to run as the Local System User.

    Refer KB: 511862