HOW TO: Create 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 create a Mapping Task in IICS using mttask REST API resource.

2. Pre-requisites

In order to create a mapping task in IICS using REST API, you need to have a reference mapping task already built in your Data Integration Service. We will take the metadata of this mapping task as reference to build a new mapping task.

In order to understand how to create a 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:

Mapping Task Name: mct_Oracle_FF_Employees

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

The requirement is to create a new mapping task on the same parameterized mapping with different source and target objects as given below

Mapping Task Name: mct_Oracle_FF_Departments

• Source Connection: Oracle
• Source Object: DEPARTMENTS
• Target Connection: Flat file
• Target Object: DEPARTMENTS.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 create a Mapping task in IICS using REST API

Creating Mapping Task through REST API implies extracting the metadata of an existing mapping task that is stored in Informatica Cloud’s Repository, update it with required changes and submit it back to the cloud repository as a new mapping task.

Follow below steps to create a 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 will be used as a reference to create a new mapping task using mttask REST API resource.
3. Update the metadata with the changes required as per the new mapping task.
4. Post the metadata with required changes to IICS Repository using mttask REST API resource to create new mapping task.

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 reference 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.

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 with the changes required as per the new mapping task

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

In our example, I will replace all occurrences of source object EMPLOYEES with DEPARTMENTS and target object EMPLOYEES.csv with DEPARTMENTS.csv in the response extracted. The mapping task name also will be updated from mct_Oracle_FF_Employees to mct_Oracle_FF_Departments.

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 to create mapping task

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

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

Body:
The updated JSON metadata of the reference mapping task.

Once the request is successful, verify the mapping task in Informatica Cloud to see if the new mapping task is created as expected.

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

If you have requirement to build a large number of 1:1 mappings or even replicate a set of mappings with same transformation logic with different sources and targets, creating mapping tasks through IICS REST API is recommended.

Note that if you requirement is to create a mapping with different sources and targets, make sure they are parameterized in mapping and values are passed through mapping task.

If your source and target is configured at mapping level, the same cannot be updated using mttask resource at the mapping task level.

5. Automating Mapping Task creation in IICS

Now you might be wondering how to automate the whole process. The solution is to build a script which takes input as the mapping task names and other required parameters like connection and object names.

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: