MasterTemplate

Use this resource to request the details for a Visio template or the details of all Visio templates in the organization. You can create or update a Visio template, and request a list of mapping tasks that use the template. You can also delete a Visio template.

GET Request

To request the details of all Visio templates in the organization, use the following URI:

/api/v2/masterTemplate

To request the details of a particular Visio template, include the Visio template ID or Visio template name in the URI. Use one of the following URIs:

/api/v2/masterTemplate/<id>
/api/v2/masterTemplate/name/<name>

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

/api/v2/masterTemplate/name/my%20Visio%20template

To request a list of mapping tasks that use a Visio template, use the Visio template ID in the following URI:

/api/v2/masterTemplate/<id>/tasks

GET Response

If successful, returns the masterTemplate object for the requested Visio template. If you request the details for all Visio templates, returns the masterTemplate object without parameter details for every Visio template in the organization.
Returns the error object if errors occur.
The masterTemplate object includes the following attributes:

Field

Type

Description

id

String

Visio template ID.

orgId

String

Organization ID.

name

String

Visio template name.

description

String

Description of the Visio template.

createTime

dateTime

Time the Visio template was created.

updateTime

dateTime

Last time the Visio template was updated.

createdBy

String

User who created the Visio template.

updatedBy

String

User who last updated the Visio template.

diFileRecordId

String

ID of the Visio template XML file.

templateImageId

String

ID of the Visio template image file.

parameters

String

Parameters used in the Visio template. Includes an mtParameter object for each parameter.

id

Long

Included in the mtParameter object.
Parameter ID

name

String

Included in the mtParameter object.
Parameter name.

label

String

Included in the mtParameter object.
Parameter label

type

String

Included in the mtParameter object.
Parameter type

description

String

Included in the mtParameter object.
Parameter type

customFuncId

String

Included in the mtParameter object.
Mapplet ID for mapplet type parameters.

uiProperties

String

Included in the mtParameter object.
Display property for the parameter. Includes the following information:
cnxtype. Connection type for the parameter.
logcnx. Logical connection.
order. Display order.
wizstep. Wizard step to display the parameter.
default. Default value.
visible. Whether the parameter is visible.
editable. Whether the parameter is editable.
required. Whether the parameter is required.
paramtype. UI control type for string parameters. Returns one of the following responses:
Condition. Filter condition input control.
Expression. Expression editor input control.
Field. Field selection input control.
Fieldmap. Field mapping input control. Includes the following attributes:
lefttitle. Left title for the field mapping display.
righttitle. Right title for the field mapping display.
leftfs. Set of fields to display in the left table of the field mapping display.
rightfs. Set of fields to display in the right table of the field mapping display.
leftfilter. Regular expression to limit the fields that display in the left table of the field mapping display.
rightfilter. Regular expression to limit the fields that display in the right table of the field mapping display.
staticlist. List of fields to display on the right side of the field mapping display.

sessionAttrs

String

General and performance session properties for the task. Can include values for the following attributes:
Write Backward Compatible Session Log File. Writes the session log to a file
Session Log File Name. Name for the session log.
Session Log File Directory. Directory where the session log is saved.
$Source Connection Value. Source connection name.
$Target Connection Value. Target connection name.
Treat Source Rows as. When the mapping task reads source data, it marks each row with an indicator to specify the operation to perform when the row reaches the target:
Insert. All rows are marked for insert into the target.
Update. All rows are marked for update in the target.
Delete. All rows are marked for delete from the target.
Data Driven. The task uses the Update Strategyobject in the data flow to mark the operation for each source row.
Commit Type. Commit type to use:
Source. Performs commits based on the number of source rows.
Target. Performs commits based on the number of target rows.
User Defined. Performs commits based on the commit logic defined in the Visio template.
If you do not configure a commit type, the task performs a target commit.
Commit Interval. Interval in rows between commits. If you do not configure a commit interval, the task commits every 10,000 rows.
Commit on End of File. Commits data at the end of the file. Returns true or false.
Rollback Transactions on Errors. If the task encounters a non-fatal error, you can choose to roll back the transaction at the next commit point.
When the task encounters a transformation error, it rolls back the transaction if the error occurs after the effective transaction generator for the target.
Java Classpath. Java classpath to use.
DTM Buffer Size. Amount of memory allocated to the task from the DTM process.
Incremental Aggregation. Performs incremental aggregation. Returns true or false.
Reinitialize Aggregate Cache. Overwrites existing aggregate files for an incremental aggregation task. Returns true or false.
Enable High Precision. Processes the Decimal data type to a precision of 28. Returns true or false.
Session Retry on Deadlock. The mapping task retries a write on the target when a deadlock occurs. Returns true or false.

wizardMetadata

Metadata for the mapping task wizard steps. Includes an mtWizardStep object for each step.

name

String

Included in the mtWizardStep object.
Name of the step.

title

String

Included in the mtWizardStep object.
The title of the step, displayed in the mapping task wizard user interface.

POST Request

To update a Visio template, use the Visio template ID in the following URI. To create a new Visio template, omit the optional Visio template ID

/api/v2/masterTemplate/<id>

You can submit a partial update using partial mode. If you want to update a field in the mtParameter object using partial mode, you must include the name or type fields. To submit a request using partial mode, use a JSON request and include the following line in the header:

Update-Mode=PARTIAL

You can use the following attributes in a masterTemplate object:

Field

Type

Required

Description

name

String

Yes

Name of the Visio template.

description

String

Description of the Visio template.

diFileRecordId

String

Yes

Visio template XML file ID.
Use the ID returned when you upload the file to the organization with the fileRecord resource.

templateImageId

String

Visio template image file ID.
This ID is returned when you upload the file to the organization with the fileRecord resource.

parameters

Object that defines parameters associated with the template. Use an mtParameter object to define each parameter.

name

String

Yes

Include in the mtParameter object.
Key field for the mtParameter collection.
Parameter name.

label

String

Include in the mtParameter object.
Parameter label.

type

String

Yes

Include in the mtParameter object.
Key field for the mtParameter collection.
Parameter type. Use one of the following values:
STRING
SOURCE
TARGET
MAPPLET
LOOKUP

descriptions

String

Include in the mtParameter object.
Parameter description.

customFuncId

String

Include in the mtParameter object.
Mapplet ID for mapplet type parameters.

uiProperties

String

Include in the mtParameter object.
Display property for the parameter. Use a UIPropertyType object to define the following display properties:
cnxtype. Connection type for the parameter. Use a valid connection type. For more information, see the connection resource.
logcnx. Logical connection.
order. Display order.
wizstep. Wizard step to display the parameter.
default. Default value.
visible. Whether the parameter is visible. Use True or False.
editable. Whether the parameter is editable. Use True or False.
required. Whether the parameter is required. Use True or False.
paramtype. UI control type for string parameters. Use one of the following values:
Condition. Filter condition input control.
Expression. Expression editor input control.
Field. Field selection input control.
Fieldmap. Field mapping input control. Include the following attributes:
lefttitle. Left title for the field mapping display.
righttitle. Right title for the field mapping display.
leftfs. Set of fields to display in the left table of the field mapping display.
rightfs. Set of fields to display in the right table of the field mapping display.
leftfilter. Regular expression to limit the fields that display in the left table of the field mapping display.
rightfilter. Regular expression to limit the fields that display in the right table of the field mapping display.
staticlist. List of fields to display on the right side of the field mapping display. Use instead of rightfs.
List field names and associated data types separated by a line break or semicolon.

sessionAttrs

String

Include in the mtParameter object.
General and performance session properties for the task. Can include values for the following attributes:
Write Backward Compatible Session Log File. Writes the session log to a file
Session Log File Name. Name for the session log.
Session Log File Directory. Directory where the session log is saved.
$Source Connection Value. Source connection name.
$Target Connection Value. Target connection name.
Treat Source Rows as. When the mapping task reads source data, it marks each row with an indicator to specify the operation to perform when the row reaches the target:
Insert. All rows are marked for insert into the target.
Update. All rows are marked for update in the target.
Delete. All rows are marked for delete from the target.
Data Driven. The task uses the Update Strategyobject in the data flow to mark the operation for each source row.
Commit Type. Commit type to use:
Source. Performs commits based on the number of source rows.
Target. Performs commits based on the number of target rows.
User Defined. Performs commits based on the commit logic defined in the Visio template.
If you do not configure a commit type, the task performs a target commit.
Commit Interval. Interval in rows between commits. If you do not configure a commit interval, the task commits every 10,000 rows.
Commit on End of File. Commits data at the end of the file. Returns true or false.
Rollback Transactions on Errors. If the task encounters a non-fatal error, you can choose to roll back the transaction at the next commit point.
When the task encounters a transformation error, it rolls back the transaction if the error occurs after the effective transaction generator for the target.
Java Classpath. Java classpath to use.
DTM Buffer Size. Amount of memory allocated to the task from the DTM process.
Incremental Aggregation. Performs incremental aggregation. Returns true or false.
Reinitialize Aggregate Cache. Overwrites existing aggregate files for an incremental aggregation task. Returns true or false.
Enable High Precision. Processes the Decimal data type to a precision of 28. Returns true or false.
Session Retry on Deadlock. The mapping task retries a write on the target when a deadlock occurs. Returns true or false.

wizardMetadata

Metadata for the mapping task wizard steps. Include an mtWizardStep object for each step.

name

String

Included in the mtWizardStep object.
Name of the step.

title

String

Included in the mtWizardStep object.
The title of the step, displayed in the mapping task wizard user interface.

POST Response

If the request to create or update a Visio template is successful, returns the master template object for the Visio template that you created or updated.
Returns the error code if errors occur.

DELETE Request

To delete a Visio template, use the Visio template ID in the following URI:

/api/v2/masterTemplate/<id>

DELETE Response

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

GET Example

To request a list of tasks that use a Visio template with an ID of 000043T1000003G, you might use the following request:

GET <serverUrl>/api/v2/masterTemplate/000043T1000003G/tasks 
Accept: application/xml
icSessionId: <icSessionId>

If successful, returns the mtTask object with id, orgId, name, and masterTemplateId for each task that uses the Visio template