HOW TO: Update Mapping Task in IICS using REST API?

1. Introduction to mttask REST API resource

Informatica Cloud offers several APIs which lets you access the information from your Informatica Intelligent Cloud Services organization. We have discussed about what is Informatica Cloud REST API and REST API in general in our previous article – Overview of Informatica Cloud (IICS) REST API and different ways to access it.

mttask is a Informatica Cloud REST API resource which let you extract the details of a Mapping Task. It also lets you create, update or delete a mapping task.

In this article let us understand how we can update Mapping Task in IICS using mttask REST API resource.

2. Problem Statement

In order to understand how to update the mapping task using REST API, let us take a simple scenario as an example.

I have a simple mapping with only source and target transformations which are completely parameterized i.e. the connection and the object in both source and target are parameterized and the values needs to be passed from the mapping task.

I have built a mapping task on top of parameterized mapping with following values for parameters:

• Source Connection: Oracle
• Source Object: EMPLOYEES
• Target Connection: Flat file
• Target Object: EMP.csv

The requirement is to update the target object name to EMPLOYEES.csv

Let us understand how this can be achieved using IICS REST API in the next steps of the article. We will be using Postman to make the REST API calls for the demonstration purpose.

3. Steps to update Mapping task in IICS using REST API

Updating Mapping Task through REST API implies updating the metadata of the mapping task that is stored in Informatica Cloud’s Repository.  In this process we extract the metadata of the task, update it with required changes and submit it back to the cloud repository.

Follow below steps to update Mapping task in IICS using mttask REST API resource

1. Login to Informatica and get icSessionId and serverUrl of your account using IICS REST API Login resource.
2. Get the metadata of the mapping task which needs to be updated using mttask REST API resource.
3. Update the metadata with required changes.
4. Post the metadata with required changes to IICS Repository using mttask REST API resource.

3.1. Login to Informatica Intelligent Cloud Services

To access any Informatica Cloud REST API resource, you need to first login into your IICS Org using a valid Informatica Intelligent Cloud Services login credentials.

To make a REST API call, the following details needs to be filled in to complete the request.

1. Request method
2. Request URL
3. Headers
4. Body

To login in to your Informatica Intelligent Cloud Services organization using REST API Version2 resource, use the following request:

Request Method: POST

Request URL: https://dm-us.informaticacloud.com/ma/api/v2/user/login

Headers:
Content-Type: application/json
Accept: application/json

Body:
{
"@type": "login",
"username": "your-username@email.com",
"password": "your-password"
}

If the request is successful you will receive a return code as 200 OK else returns the error object if errors occur. From the response tab, collect the serverUrl and icSessionId details to use in subsequent calls.

For more detailed step-by-step process on how to make a login request using Postman, refer our article here.

3.2. Get the metadata of the mapping task

To request the details of a mapping task, you can use the task name, federated task ID, or task ID.

• Task Name is straight forward. It is the name of the task.
• Federated Task ID can be extracted from the URL when you select the mapping task. It will be the last part of the URL.
  Below is a sample URL of mapping task. The highlighted last part of the URL indicates the Federated Task ID.
  https://usw5.dm-us.informaticacloud.com/diUI/products/integrationDesign/main/mct/aTDAwPBP2AdkF7orwH1J6K

• Task ID can be found in the export ZIP file of the mapping task with attribute name as ID.

To request the details of a mapping task, Use one of the following URIs:

/api/v2/mttask/name/<task-name>
/api/v2/mttask/frs/<fed-task-id>
/api/v2/mttask/<task-id>

You need to use the above URI along with the serverUrl fetched from the login response and add Session ID in your request and submit it. Below are the complete request details:

Request Method: GET

Request URL: <serverURL>/api/v2/mttask/name/<task_name>

Headers:
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>

The JSON response of the request provides the metadata of the mapping task stored in the Informatica Cloud’s Repository. The same can also be extracted from the exported ZIP of the mapping task.

For more details on how to read the metadata of the mapping task manually,
refer our article here.

3.3. Update the metadata of the Mapping Task

Copy the GET mttask response into a notepad. Find and replace the contents you wanted to update in the metadata extracted.

In our example, I will replace all occurrences of EMP.csv with EMPLOYEES.csv in the response extracted.

The updated metadata of the task will be used as one of the input in our next step.

3.4. Post the metadata with required changes to IICS Repository

You can only use the task Id or the federated task ID to submit the POST request. The task id can be easily extracted from the response of the GET mttask request.

Once you have the updated metadata of the mapping task, submit the following request.

Request Method: POST

Request URL: <serverURL>/api/v2/mttask/<task-id>

Headers:
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>
Update-Mode: PARTIAL

Body:
The updated JSON metadata of the mapping task.

Once the request is successful, verify the mapping task in Informatica Cloud Data Integration Service to see if the changes are submitted as expected.

4. Use Cases of updating IICS Mapping Tasks using REST API

The scenario we have taken to demonstrate the update process of a mapping task using REST API is very simple. But in real time, it has some very important use cases.

For example, if you are working with Snowflake Data Cloud connector in your IICS Org and your DEV and PROD databases are in the same Snowflake account. This means your DEV and PROD databases should have a different names as you cannot create them with same name within the same Snowflake account.

In such case, when you migrate the code from your DEV to PROD IICS Org, though the Production Snowflake connection is pointing to PROD database, the metadata of the tasks imported into production still point to the DEV database and your IICS jobs fails in production. This is a real-time scenario which currently exists.

This used to be the same case with AWS S3 v2 Connector earlier. We know that s3 bucket names are a global namespace, which means every s3 bucket must have a unique name across globally. So obviously the DEV and PROD s3 buckets will be of different names. When the code migrated to PROD, though the production s3 connection is pointing to a different s3 bucket, the metadata still points to DEV s3 bucket and job used to fail. This issue is now fixed by Informatica.

The workaround to these issues is to override the database and bucket names during runtime using parameter file.

Another way of solving the issue is through updating the metadata in mapping tasks with production values using REST API as demonstrated in this article.

5. Closing Points

Now you might be wondering how to automate the whole process. If you have hundreds of mapping tasks which use Snowflake connector, how can we update the database name in metadata of all of them easily?

The solution is to build a script which loops through the list of mapping tasks which you pass as input and update a particular DEV value with PROD value.

If you are comfortable with shell or batch scripting, build a script using cURL commands to make these REST API calls. If you are comfortable with Python, you can also build the same script to make the IICS REST API calls using built-in libraries. Trust me you do not need crazy programming skills to build this script. If you have some basic understanding and with some little googling you can easily automate it.

Subscribe to our Newsletter !!

Related Articles: