Mtttask

Use this resource to request the details of a mapping task. You can also create, update, or delete a mapping task.

Note...
You cannot use the REST API to create a mapping task based on a mapping that includes a mapplet.

GET Request

To request the details of a mapping task, you can use the task ID or task name. Use one of the following URIs:

/api/v2/mttask/<id>
/api/v2/mttask/name/<name>

If you use the task name in the URI and the task name includes a space, replace the space with %20. For example:

/api/v2/mttask/name/task%20name

GET Response

Returns the mtTask object for the requested task ID or task name.
Returns the error object if errors occurred.
The following table describes attributes in an mtTask object:

id

String

Task ID.

orgId

String

Organization ID.

name

String

Task name.

description

String

Description

createTime

Date/time

Time the task was created.

updateTime

Date/time

Last time the task was updated.

createdBy

String

User who created the task.

updatedBy

String

User who last updated the task.

errorTaskEmail

Object that includes the taskEmail object for error notifications

id

String

Included in taskEmail object for errorTaskEmail.
ID.

emails

String

Included in taskEmail object for errorTaskEmail.
Email address that receives email notification when a task fails to complete.

successTaskEmail

Object that includes the taskEmail object for success notifications.

id

String

Included in taskEmail object for successTaskEmail.
ID.

emails

String

Included in taskEmail object for successTaskEmail.
Email address that receives email notification when a task completes successfull

warningTaskEmail

Object that includes the taskEmail object for warning notifications.

id

String

Included in taskEmail object for warningTaskEmail.
ID.

emails

String

Included in taskEmail object for warningTaskEmail.
Email address that receives email notification when a task completes with errors

parameters

Parameters associated with the task. Includes attributes in the mtTaskParameter object for each parameter.

id

Included in the mtTaskParameter object.
Parameter ID.

name

String

Included in the mtTaskParameter object.
Parameter name.

type

String

Included in the mtTaskParameter object.
Parameter type

text

String

Included in the mtTaskParameter object.
Parameter value

label

String

Included in the mtTaskParameter object.
Parameter label.

description

String

Included in the mtTaskParameter object.
Parameter description.

sourceConnectionId

String

Included in the mtTaskParameter object.
Source connection ID

targetConnectionId

String

Included in the mtTaskParameter object.
Target connection ID

lookupConnectionId

String

Included in the mtTaskParameter object.
Lookup connection ID

transfConnectionId

String

Included in the mtTaskParameter object.
Connection ID of mapplet. Reserved for future use.

midstreamConnectionId

String

Included in the mtTaskParameter object.
Connection ID of midstream transformation.

sourceObject

String

Included in the mtTaskParameter object.
Source object name.

sourceObjectLabel

String

Included in the mtTaskParameter object.
Source object label

targetObject

String

Included in the mtTaskParameter object.
Target object name.

targetObjectLabel

String

Included in the mtTaskParameter object.
Target object label.

lookupObject

String

Included in the mtTaskParameter object.
Lookup object name.

lookupObjectLabel

String

Included in the mtTaskParameter object.
Lookup object label.

midstreamObject

String

Included in the mtTaskParameter object.
Midstream object name

midstreamObjectLabel

String

Included in the mtTaskParameter object.
Midstream object label.

newObject

Boolean

Included in the mtTaskParameter object.
Whether the application creates a new flat file target. Returns True when it creates a target.

newObjectName

String

Included in the mtTaskParameter object.
Name of the flat file target.

operationType

String

Included in the mtTaskParameter object.
The task operation for the target.

truncateTarget

Boolean

Included in the mtTaskParameter object.
Whether the application truncates a database target before writing to it. Returns True when it truncates the target

srcFFAttrs

Included in the mtTaskParameter object.
Object that contains the source file attributes in the flatFileAttrs object.

tgtFFAttrs

Included in the mtTaskParameter object.
Object that contains the target file attributes in the flatFileAttrs object.

lkpFFAttrs

Included in the mtTaskParameter object.
Object that contains the lookup file attributes in the flatFileAttrs object.

flatFileAttrs

Object that includes attributes for the source, target, and lookup files.

id

Long

Included in the flatFileAttrs object.
Field ID.

delimiter

String

Included in the flatFileAttrs object.
Character used to separate fields

textQualifier

String

Included in the flatFileAttrs object.
Quote character that defines the boundaries of text strings

escapeChar

String

Included in the flatFileAttrs object.
Character immediately preceding a field delimiter character embedded in an unquoted string, or immediately preceding the quote character in a quoted string

headerLineNo

Int

Included in the flatFileAttrs object.
Number of header lines

firstDataRow

Int

Included in the flatFileAttrs object.
The row number where the data begins in the file.

customFuncCfg

Included in the mtTaskParameter object.
Object that defines configuration for mapplets used in the task. Includes attributes in the customFuncConfig object for each mapplet.

id

Long

Included in the customFuncConfig object.
Mapplet ID.

connections

Included in the customFuncConfig object.
Object to define connections used in a mapplet. Includes information in the pcsConnection object for each connection

id

Long

Included in the pcsConnection object.

name

String

Included in the pcsConnection object.
Connection name.

type

String

Included in the pcsConnection object.
Connection type

subtype

String

Included in the pcsConnection object.
Connection subtype.

description

String

Included in the pcsConnection object.
Description of the connection.

connectionId

String

Included in the pcsConnection object.
Connection ID.

showBusinessNames

String

Included in the mtTaskParameter object.
Whether the task displays business names. Returns True when it shows business names.

naturalOrder

Boolean

Included in the mtTaskParameter object.
The order that the task uses to display fields. Returns True for the order returned by the connection. Returns False for alphabetic order.

isRESTModernSource

Boolean

Included in the mtTaskParameter object.
Always set to True to enable extended objects

customQuery

String

Included in the mtTaskParameter object.
The custom query specified in Mapping Designer or mapping task query options

overriddenFields

Included in the mtTaskParameter object.
Changes to field metadata in the mapping task. Includes information in the mtTaskOverriddenField object for each overridden field

name

String

Included in the mtTaskOverriddenField object.
Field name.

type

String

Included in the mtTaskOverriddenField object.Field type.

precision

Int

Included in the mtTaskOverriddenField object.Length of the field in bytes.

scale

Int

Included in the mtTaskOverriddenField object.Number of digits after the decimal point for numeric values.

tgtFieldRefs

String

Included in the mtTaskParameter object.
Salesforce field reference IDs.

extendedObject

Included in the mtTaskParameter object.
The source or target with more than one object joined

targetUpdateColumns

String

Included in the mtTaskParameter object.
List of column names used to update records in the target object.

runtimeAttrs

String

Included in the mtTaskParameter object.
Advanced connection properties for connections used in a task.
Use a runtimeAttrs object to define key-value pairs of advanced connection properties. Use an entry object for each key-value pair.
For the attribute name, use the advanced connection property name as displayed in the Data Integration user interface.
For more information about advanced connection properties, see the Data Integration Help

dataFormat

Included in the mtTaskParameter object.
Data format provided by the connector.
Includes attributes in the dataFormat object for each connector.
The dataFormat object is not applicable to all connectors. To see if dataFormat is applicable to the connectors you are using, see the relevant connector guides

formatId

Included in the dataFormat object.
Data format type provided by the connector, such as FLAT, AVRO, PARQUET, JSON, or XM

dataFormatAttributes

Included in the dataFormat object.
Format attributes for the data format type. For example, for a flat file, the dataFormatAttributes object includes values such as escapeChar, delimiter, and qualifier

sequences

Defines values for the Sequence Generator transformation. Includes the sequenceDefinition object for each sequence transformation.

txName

String

Included in the sequenceDefinition object.
Name of the Sequence Generator transformation

initialValue

String

Included in the sequenceDefinition object.
The initial value of the sequence.

currentValue

String

Included in the sequenceDefinition object.
The value used for the last row added to the transformation.

inOutParameters

In-out parameter used in the task. Includes a mtTaskInOutParameter object for each in-out parameter.

id

String

Included in the mtTaskInOutParameter object.
Parameter ID.

name

String

Included in the mtTaskInOutParameter object.
Parameter name.

description

String

Included in the mtTaskInOutParameter object.
Description of the paramete

initialValue

String

Included in the mtTaskInOutParameter object.
Initial value for the parameter.

datatype

String

Included in the mtTaskInOutParameter object.
Data type of the parameter

precision

String

Included in the mtTaskInOutParameter object.
Precision of the parameter.

scale

String

Included in the mtTaskInOutParameter object.
Scale of the parameter.

retentionPolicy

String

Included in the mtTaskInOutParameter object.
Determines when the task retains the current value.

aggregationType

String

Included in the mtTaskInOutParameter object.
Determines the final current value of the parameter when the task runs.

currentValue

String

Included in the mtTaskInOutParameter object.
Current value for the paramete

agentId

String

Agent that runs the task.

lastRunTime

Date/time

Time the task last run.

masterTemplateId

String

Visio template ID. Returned when a Visio template is the basis of the task

mappingId

String

Mapping ID. Returned when a mapping is the basis for the task

scheduleId

String

Schedule associated with the task, if any.

shortDescription

String

The first 50 characters of the description.

sessionProperties

String

Advanced session properties associated with the task.
Includes advanced session properties in a sessionProperties object.

outboundMessageUrlToken

String

Outbound message URL token for the task, if it exists.

outboundMessageUrlQueueTime

Long

Outbound message URL queue time for the task, if it exists.

runtimeEnvironmentId

String

Runtime environment used for the task.

preProcessingCmd

String

Command to run before the task.

postProcessingCmd

String

Command to run after the task completes.

parameterFileName

String

The name of the parameter file used in the task.

maxLogs

Long

Number of session log files and import log files Data Integration retains.

verbose

Boolean

Whether Data Integration generates additional data in the logs to use for troubleshooting purposes. Returns True or False.

POST Request

To update a mapping task, use a mapping task ID in the following URI. To create a mapping task, omit the optional task ID.

/api/v2/mttask/<id>

You can submit a partial update using partial mode. If you want to update a field that is within a collection using partial mode, you must include the key field for the collection. The following table lists the collections in the mttask resource and the corresponding key fields:

Collection

Key Field

mtTaskInOutParameter

name

sequenceDefinition

txtName

mtTaskOverriddenField

name

mtTaskParameter

name
type

To submit a request using partial mode, use a JSON request and include the following line in the header:

Update-Mode=PARTIAL

The following table describes the attributes you can include in an mtTask object:

POST Response

If successful, returns the mtTask object that you created or updated. Returns the error object if errors occur.

DELETE Request

To delete a mapping task, use the task ID in the following URI:

/api/v2/mttask/<id>

DELETE Response

Returns the 200 response code if the request is successful.
Returns the error object if errors occur.

POST Example

To create a new mapping task with XML, you might use the following request:

POST <serverUrl>/api/v2/mttask
Content-Type: application/xml
Accept: application/xml
icSessionId: <icSessionId>

<mtTask>
  <errorTaskEmail>
    <taskEmail>
      <emails>[email protected], [email protected]</emails>
    </taskEmail>
  </errorTaskEmail>
  <successTaskEmail>
    <taskEmail>
      <emails>[email protected]</emails>
    </taskEmail>
  </successTaskEmail>
  <warningTaskEmail>
    <taskEmail>
      <emails>[email protected], [email protected]</emails>
    </taskEmail>
  </warningTaskEmail>
  <parameters>
    <mtTaskParameter>
      <name>sort convert plugin</name>
      <type>MAPPLET</type>
    </mtTaskParameter>
  </parameters>
  <parameters>
    <mtTaskParameter>
      <name>DB lookup</name>
      <type>LOOKUP</type>
    </mtTaskParameter>
  </parameters>
  <sessionProperties>
      <entry>
         <key>Java Classpath</key>
         <value>C:/test/classpathnew</value>
      </entry>
      <entry>
         <key>Pushdown Optimization</key>
         <value>To Source</value>
      </entry>
      <entry>
         <key>Write Backward Compatible Session Log File</key>
         <value>no</value>
      </entry>
   </sessionProperties>
  <runtimeEnvironmentId>00000398D00000004</runtimeEnvironmentId>
  <sequences>
    <sequenceDefinition>
      <txName>SeqGen1</txName>
      <initialValue>1</initialValue>
      <currentValue>62</currentValue>
    </sequenceDefinition>
  </sequences>
  <preProcessingCmd>echo CurrentDate is 'date'</preProcessingCmd>
  <postProcessingCmd>echo PR-PostProcess</postProcessingCmd>
  <masterTemplateId>00034234M00000R</masterTemplateId>
</mtTask>

A successful request returns the mtTask object.

Mask Rule Parameter Attributes for Masking Techniques

Define the parameter attribute values of a mask rule parameter when you run the mapping task. The attributes that you define depend on the masking technique that you apply.

For example, to mask a billing city field with the Substitution City masking technique, define the following attributes:

[
  {
    "referenceField": "BillingCity",
    "pcType": "string",
    "precision": 40,
    "paramMap": {
      "isSeeded": "TRUE",
      "seedValue": "190",
      "dicName": "informatica_mask_us_towns.dic",
      "outputPort": "TOWNNAMES",
    },
    "maskingType": "Substitution City"
  }
]

The following table lists the attributes that you define for each masking technique:

Masking Technique

Attributes

Credit Card

isSeeded
seedValue
keepCardIssuer
targetIssuer

Custom Substitution

DicConn
DicName
outputPort
isSeeded
seedValue

Email address

sSeeded
seedValue

IP address

isSeeded
seedValue

Key Date

isSeeded
seedValue

Key Numeric

override
isSeeded
seedValue

Key String

isSeeded
seedValue
useMaskFormat
maskFormat
useSrcFilter
srcFilterOption
srcFilterStr
useTargetFilter
targetFilterOption
targetFilterStr

Phone

isSeeded
seedValue

Random Date

useRange
minWidth
maxWidth
useBlurring
blurringUnit
blurLow
blurHigh

Random Numeric

useRange
minWidth
maxWidth
useBlurring
blurringOption
blurLow
blurHigh

Random String

useRange
minWidth
maxWidth
useMaskFormat
useSrcFilter
srcFilterStr
useTargetFilter
targetFilterOption
targetFilterStr

SIN

isSeeded
seedValue
startDigit
startDigitValue

SSN

isSeeded
seedValue

Substitution City

isSeeded
seedValue
DicName
outputPort

Substitution Country

isSeeded
seedValue
DicName
outputPort

Substitution Female Name

isSeeded
seedValue
DicName
outputPort

Substitution Last Name

isSeeded
seedValue
DicName
outputPort

Substitution Male Name

isSeeded
seedValue
DicName
outputPort

Substitution Name

isSeeded
seedValue
DicName
outputPort

Substitution Position

isSeeded
seedValue
DicName
outputPort

Substitution State

isSeeded
seedValue
DicName
outputPort

Substitution Street

isSeeded
seedValue
DicName
outputPort

Substitution U.S. ZIP code

isSeeded
seedValue
DicName
outputPort

URL

isSeeded
seedValue

Mask Rule Parameter Attribute Values

Define the required parameter attribute values when you run the mapping task.

The following table describes the attributes and values that you define for the mask rule parameter:

Attribute

Description

blurHigh

Required. The higher bound for blurring. You can specify the value in digits.
Default is 0.

blurLow

Required. The lower bound for blurring. You can specify the value in digits.
Default is 0

blurringOption

Required. The unit of blurring for a numeric port. You can specify the following values:
Percent. Blurs the data based on a percent value.
Fixed. Blurs the data based on a fixed value.

blurringUnit

Required. The unit of blurring for a date port. You can specify the following values:
Year. Blurs the year value.
Month. Blurs the month value.
Day. Blurs the day value.
Hour. Blurs the hour value.
Minute. Blurs the minute value.
Second. Blurs the second value.
Default is Year

delimiter

Delimiter to separate the first name and last name in a masked email address. You can specify the value as:
.

  • _

DicConn

The connection that contains the dictionary files. Create a flat file connection that points to the directory with the dictionary files. Specify the flat file connection name.

dicName

The name of the flat file dictionary file. The dictionary file must be present in the rdtmDir directory of the Secure Agent.

domainConstantValue

Domain name to use in masked email addresses.
Default is company.com.

expText

An attribute to configure an expression.

firstNameColumn

The first name column to use in masked email addresses. Specify the name of the port.

firstNameLength

The length of the first name in a masked email address. You can specify the value in digits.
Default is 5

isSeeded

An attribute to configure repeatable output. You can specify the following values:
TRUE. Masks the data with repeatable output. When true, specify a seed value.
FALSE. Masks the data with random output.
Default is TRUE.

keepCardIssuer

Masks a credit card field with a credit card number from the same issuer. You can specify the following values:
TRUE. Retains the same card issuer in the masked data.
FALSE. Uses a specified card issuer in the masked data.
When false, define the targetIssuer attribute.
Default is TRUE.

lastNameColumn

The last name column to use in masked email addresses. Specify the name of the port.

lastNameLength

The maximum length of the last name in masked email addresses. You can enter the value in digits.
Default is 5

maskFormat

Defines the type of character to substitute for each character in the input data. You can limit each character to an alphabetic, numeric, or alphanumeric character type.
Use the following characters to define a mask format:
A. Alphabetic
D. Digits 0-9
N. Alphanumeric
X. Any character
R. Rest of the characters.
Specify the value as ADNX+R. R must appear as the last character. For example, to ensure the masked output begins with an alphabet, enter the value as A+R.
Default is R.

maxWidth

Required. The minimum value for the range. Enter the value in digits.
Default is 0

maxWidth

Required. The maximum value for the range. Enter the datetime value.
Default is 01/19/2038 03:13:59.

minWidth

Required. The minimum value for the range. Enter the datetime value.
Default is 01/01/1970 00:00:00.

minWdth

Required. The minimum value for the range. Enter the value in digits.
Default is 0.

outputPort

The output port column from the dictionary.

seedValue

The seed value. Specify a value between 1 and 999.
Default is 190.

srcFilterOption

Required. The type of filter to apply to source filter characters. You can specify the following values:
Mask Only. Masks only the specified characters in the source.
Mask all except. Masks all characters in the source except the characters specified.

srcFilterStr

Required. Defines the characters in the source string that you want to mask

startDigit

Required. Defines the first digit of the masked SIN. You can specify the following values:
TRUE. Uses the digit that you specify as the first digit of the masked SIN.
FALSE. Uses a random digit as the first digit of the masked SIN.
Default is FALSE. When true, define the startDigitValue attribute.

startDigitValue

Required. Defines the first digit of the masked SIN. Specify a value between 0 and 9.
Default is 0.

targetFilterOption

Required. The type of filter to apply on target filter characters. You can specify the following values:
Use Only. Uses only the target characters that you specify.
Use All Except. Uses all characters in the target except what you specify.

targetFilterStr

Required. Substitutes the characters in a target string with the characters that you define in target filter characters. For example, enter the following characters to configure the masked output to contain all uppercase alphabetic characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ.

targetIssuer

Required. Masked values contain credit card numbers from the issuer that you select. You can specify the following values:
ANY
JCB
VISA
AMEX
DISCOVER
MASTERCARD

useBlurring

Required. Masks dates based on a variance that you apply to a unit of the date. The masked date is within the variance. You can specify the following values:
TRUE. Applies a variance that you specify on a unit of the date.
FALSE. Does not apply a variance.
Default is FALSE.

useMaskFormat

Specifies a mask format. You can specify the following values:
TRUE. Masks the data based on a format that you specify.
FALSE. Masks the data in a random format.
Default is TRUE. If true, define the maskFormat attribute.

useRange

Required. Specifies a return value between the minimum and maximum values of the range based on field precision. You can specify the following values:
TRUE. Masks the data within a range that you specify.
FALSE. Does not use a specified range to mask the data.
To define the range, configure the minimum and maximum ranges or configure a blurring range based on a variance from the original source value.
Default is FALSE.

useSrcFilter

Specifies the characters in the source string that you want to mask. You can specify the following values:
TRUE. Masks the characters in the source string that you specify.
FALSE. Masks random characters in the source string.
Default is FALSE.

useTargetFilter

Specifies the characters to use in the masked string. You can specify the following values:
TRUE. Uses characters that you specify in the masked string.
FALSE. Uses random characters in the masked string.
Default is FALSE