How to trigger IICS Tasks from Command Line using RunAJob Utility?

1. Introduction

Informatica provides command line programs which makes it much easier to perform tasks remotely. They are much powerful and provides efficient way of performing tasks.

PMCMD is such a command line program available in Informatica Powercenter used to trigger workflows in command line mode.

Informatica Cloud provides RunAJob utility to trigger tasks from command Line in Linux or Windows.

Let us discuss in detail about the RunAJob utility available in Informatica Cloud.

2. What is RunAJob utility?

RunAJob utility is a command line tool used to trigger IICS Data Integration tasks.The RunAJob utility internally calls IICS REST API service to trigger tasks.

One can use REST API to trigger the tasks directly. But a proper understanding of REST framework is required to implement the tasks.

The RunAJob utility bundles all the required functionalities of REST API there by making it easy to the end user to perform tasks by just passing only the required details to the tool such as task name and type.

3. RunAJob utility Requirements

Your organization must have a license to use the RunAJob utility.

• To verify if your organization have the required license, log in to your Informatica account and go to Administrator > Licenses > Custom Licenses at the bottom of the page.
• If your organization has the license to use RunAJob utility, it can be found under the following location:

<Secure Agent directory>\apps\runAJobCli

• Informatica Intelligent Cloud Services Free trail do not provide access to RunAJob utility by default.

To use the RunAJob utility, the Secure Agent machine must have latest Java version installed.

4. RunAJob utility Setup

To complete the set up process, you need to create two files and place them in the RunAJob utility folder (<Secure Agent directory>\apps\runAJobCli)

• restenv.properties
• log4j.properties

Template files are provided along with the package which can be used to create the required files and are also available under RunAJob utility folder.

• restenv_default.properties
• log4j_default.properties

Copy both the template files in the same RunAJob utility folder and rename them to the restenv.properties and log4j.properties.

4.1. Configuring restenv.properties File

The restenv_default.properties file specifies login credentials and job polling behavior.

The contents of the file will be as below.

baseUrl=https://dm-us.informaticacloud.com/ma
username=username
password=password
ACTIVITYMONITORWAIT=2000
TOTALWAIT=5000
PROXYHOST=
PROXYPORT=
RETRYCOUNT=

Enter the details of the username and password to login and use the default baseUrl in the restenv.properties file to connect to Informatica Intelligent Cloud Services.

The other parameters are

With the default settings the utility checks the Activity monitor for every 5 seconds (TOTALWAIT) until 6 (RETRYCOUNT) times for the job status. If the job keeps running even after the completion of retry attempts, the command will exit with return code 6 (which means the job is running) and the job will continue to run in Informatica Intelligent Cloud Services.

4.2. Configuring log4j.properties File

The log4j.properties file is used to specify the level of detail to return in the log file.

If you want the log to return basic information about the job such as user ID, job ID, and time the task was initiated, set the level of detail to Info.

If you want the log to return all of the job details, set the level of detail to Debug.

If you are not sure about the settings, copy and leave the file as it is. No extra changes are required from the user.

5. How to trigger tasks from RunAJob utility?

RunAJob utility comes with preloaded scripts which can be used to trigger the tasks.

• If the secure agent is installed on Linux, use cli.sh script to trigger the tasks.
• If the secure agent is installed on Windows, use cli.bat script to trigger the tasks.

The syntax to trigger the tasks from RunAJob utility is as follows

cli.sh runAJobCli -n <taskname> -t <tasktype> -w<true/false>

The syntax to trigger taskflow is slightly different and the taskflow must have been published.

cli.sh runAJobCli -t TASKFLOW -un <taskflow name>

The other arguments that can be used in syntax are as follows

6. RunAJob utility Status Codes

The utility can return the following status codes

7. Triggering tasks from Third-Party Schedulers using RunAJob utility

If you are planning to use a third party scheduler like Autosys to trigger IICS tasks in your project instead of IICS built-in scheduler, getting RunAJob utility license is a must. It makes the process very simple and easy to set up.

First you need to set up RunAJob utility on your machine as discussed in the above sections.

If you are using a third-party scheduler like Autosys, it is suggested that instead of calling directly the cli.sh script , create an intermediate script which calls the cli.sh script.

Pass the task type and task name as arguments to the intermediate script.

The advantages of calling utility through intermediate script are

• The intermediate script can be maintained in the same folder where you maintain all the scripts related to project.
• You can prevent the access to cli.sh/cli.bat script to non-admin users. Since the restenv.properties file (which holds login credentials to IICS) will be in the same folder as cli scripts, it is best to prevent the access to the entire package folder.
• Having an intermediate script to call the RunAJob utility gives much more flexibility to create custom logs to add more useful information for debugging purposes.
• If there is a requirement to pass different arguments to different type of tasks, it can be easily handled through a custom intermediate script.

For example, if you created an intermediate script “Execute_runAJobCli.sh” and you need to trigger a mapping task from Autosys, the command would be

Execute_runAJobCli.sh “MappingTaskName” “MTT”

Instead of

cli.sh runAJobCli -n MappingTaskName -t MTT -w true

Also triggering taskflows from third-party scheduler is not recommended as it does not provide any additional value or control to handle the individual tasks from the third-party scheduler.

8. Conclusion

RunAJob utility is not an agent dependent. That means we can run the utility from any server machine (not only from the sever where secure agent is installed). All you need to have is the RunAJob utility license enabled for your org and the latest java version is installed on the host server machine.

This gives much flexibility to trigger the data integration tasks remotely from any server machine.

How are the tasks scheduled in your working project? Do you prefer using a third-party scheduler over the IICS built-in scheduler? Let me know in the comments section.