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)
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.
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
|ACTIVITYMONITORWAIT||The amount of time the utility waits before retrying if an internal exception occurs, such as a login failure or network problem. Default is 2000 milliseconds.|
|TOTALWAIT||The maximum amount of time the utility waits for a job to complete before polling the activity monitor and activity log again for status. Default is 5000 milliseconds.|
|RETRYCOUNT||The number of times the utility polls for status. This parameter is used for polling the activity monitor and activity log for job status and for internal exceptions such as login failure or network problems. Default is 6.|
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.
If there is an error, the utility makes 6(RETRYCOUNT) retry attempts and waits 2 seconds(ACTIVITYMONITORWAIT) between each retry attempt.
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
|Username||-u||Informatica Intelligent Cloud Services username.|
|Password||-p||Informatica Intelligent Cloud Services password.|
|TaskId||-i||Required when the command does not include the task name or Federated Task ID.|
|Folder Path||-fp||Required when the task is not in the Default folder and the command does not include the federated task ID.|
|Federated task ID||-fi||Required when the task is not in the Default folder and the command does not include the folder path.|
|taskflowUniqueName||-un||Taskflow unique name. Required to run a taskflow.|
|Task Name||-n||Name of the task.|
|Task Type||-t||Use one of the following values: |
DMASK – Masking task
DRS – Replication task
DSS – Synchronization task
MTT – Mapping task
PCS – PowerCenter task
Workflow – Linear taskflow
TASKFLOW – Taskflow
|Wait Flag||-w||Determines whether to wait for the job to complete or run the job in the background.|
|debug||-d||Display debugging information.|
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”
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.
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.