Connection

Use this resource to request connection details for an organization. You can also use this resource to create, update, test, and delete a connection.

Details GET Request

You can request the following details using a connection GET request:

  • Details of all connections in the organization.
  • Details for a particular connection in the organization.
  • List of objects that you can use as a source or target with a particular connection.
  • List of connections of a specified type associated with a Secure Agent or runtime environment.
  • Metadata details for a specified connection
    Note: Do not use connections with names that begin with "DI Data Preview_".

Details of all connections in the organization:

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

/api/v2/connection

Details of a particular connection
To request the details of a particular connection, include the connection ID or name in the URI. Use one of the following URIs

/api/v2/connection/<id>

/api/v2/connection/name/<name>

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

/api/v2/connection/name/my%20connection

List of objects that you can use as a source or target

You can request the objects that you can use as a source or target. A maximum of 200 objects can be returned for one request. To request source or target objects, you can include either the connection ID or connection name in the URI. Use one of the following URIs:

/api/v2/connection/source/<id>

/api/v2/connection/target/<id>

/api/v2/connection/source/name/<name>

/api/v2/connection/target/name/<name>

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

/api/v2/connection/target/name/my%20connection

If you expect to receive a large number of objects, you might want to filter the results. To filter the results, include the connection ID and the searchPattern parameter. To use the searchPattern parameter, use the following URI:

/api/v2/connection/<source or target>/<id>?searchPattern=<pattern>

For example, the following request returns source objects that include "abc" in the object name:

/api/v2/connection/source/002D420000000J?searchPattern=abc

List of connections of a specified type associated with a Secure Agent or runtime environment

To request a list of connections by Secure Agent ID and connection type, use the following URI:

/api/v2/connection/search?agentId=<agentId>&uiType=<uiType>

To request a list of connections by runtime environment ID and connection type, use the following URI:

/api/v2/connection/search?runtimeEnvironmentId=<runtimeEnvironmentId>&uiType=<uiType>

If you pass both agentId and runtimeEnvironmentId, the service uses runtimeEnvironmentId and ignores agentId. If you pass only agentId, the service translates agentId into its corresponding runtimeEnvironmentId before it saves the resource to the repository.

Metadata details for a specified connection
To request metadata details for a specified connection, use the following URI:

/api/v2/connection/source/<connection ID>/metadata

/api/v2/connection/target/<connection ID>/metadata

The metadata is returned in the runtimeAttribute object which contains the following attributes:

  • name
  • dataType
  • defaultValue
  • label
  • mandatory
  • maxLength
  • sessionVarAllowed
  • possibleValues

Use the following connection request URI attributes:

Field

Type

Required

Description

agentId

String

Secure Agent ID

runtimeEnvironmentId

String

Runtime environment ID.

uiType

String

Yes

Connection type. Use one of the following options:

  • CSVFile. CSV flat file.
    
  • FTP.
    
  • MS_ACCESS.
    
  • MSD. Microsoft Dynamics CRM.
    
  • MySQL.
    
  • ODBC.
    
  • Oracle.
    
  • OCOD. Oracle CRM On Demand.
    
  • Salesforce.
    
  • SFTP. Secure FTP.
    
  • SAP_ALE_IDoc_Reader. SAP IDoc Reader.
    
  • SAP_ALE_IDoc_Writer. SAP IDoc Writer.
    
  • SqlServer. Microsoft SQL Server 2000.
    
  • SqlServer2005. Microsoft SQL Server 2005.
    
  • SqlServer2008. Microsoft SQL Server 2008.
    
  • SqlServer2012. Microsoft SQL Server 2012.
    
  • SqlServer2014. Microsoft SQL Server 2014.
    
  • SqlServer2016. Microsoft SQL Server 2016.
    
  • SqlServer2017. Microsoft SQL Server 2017.
    
  • TOOLKIT. Informatica Cloud Connector. Also use for NetSuite connections.
    
  • WebServicesConsumer. Web Service. 
    

Details GET Response

Returns the connection object for the requested connection ID. If you request information for all connections in the organization, returns a connection object for each connection in the organization.
If you request a list of connections based on the runtime environment ID and connection type, returns a connection object for each connection that matches the requirements.
If you request a list of source or target objects available for the requested connection ID, returns the connListItem object for each available object.
Returns the error object if errors occur.
The connection object includes different information based on connection type.
The following table describes attributes included in a connection object:

Field

Type

Description

id

String

Connection ID.

orgId

String

Organization ID.

name

String

Connection name.

description

String

Description of the connection.

createTime

Date/time

Time the connection was created.

updateTime

Date/time

Last time the connection was updated.

createdBy

String

User who created the connection.

updatedBy

String

User who last updated the connection.

agentId

String

Secure Agent ID for Flat File, FTP/SFTP, Microsoft SQL Server, MS Access, MySQL, ODBC, Oracle, and Web Service connections.

runtimeEnvironmentId

String

Runtime environment used by the connection. This is the Runtime Environment field in the user interface. In the response returned to the user interface, this attribute is named agentGroupId.

instanceName

String

Microsoft SQL Server instance name.

host

String

Host name for FTP/SFTP, Microsoft SQL Server, MySQL, and Oracle connections.

domain

String

Domain name for Microsoft Dynamics CRM connections that use IFD or Active Directory authentication, and Web Service connections.

dateFormat

Date format for Flat File, FTP, and SFTP connections.

database

String

Returns the following information:

  • For Microsoft SQL Server and MySQL connections, returns the database name.
    
  • For Flat File connections, returns the directory.
    
  • For FTP and SFTP connections, returns the local directory.
    
  • For MS Access and ODBC connections, returns the data source name.
    
  • For Oracle connections, returns the service name.
    
  • For SAP IDoc Writer and Reader connections, returns the destination entry.
    
  • For Web Service connections, returns the service URL. 
    

codepage

Code page for Flat File, FTP, SFTP, Microsoft SQL Server, MySQL, MS Access, ODBC, Oracle, and SAP.

clientCode

String

Client code for SAP IDoc Writer connections.

authenticationType

String

Authentication type for Microsoft Dynamics CRM, Microsoft SQL Server, and Web Service connections.

adjustedJdbcHostName

String

Host name. Or host and instance name for Microsoft SQL Server connections.

accountNumber

String

Account ID for NetSuite connections.

languageCode

String

Language code for SAP IDoc Writer connections.

remoteDirectory

String

Remote directory for FTP/SFTP connections.

schema

String

Schema name for Microsoft SQL Server, ODBC, Oracle, and Web Service connections.

serviceUrl

String

Service URL for Microsoft Dynamics CRM, Oracle CRM On Demand, and Salesforce connections.

shortDescription

String

The first 50 letters of the description.

type

String

Connection type returns one of the following responses:

  • CSVFile. CSV flat file.
    
  • FTP.
    
  • MS_ACCESS.
    
  • MSD. Microsoft Dynamics CRM.
    
  • MySQL.
    
  • ODBC.
    
  • Oracle.
    
  • OCOD. Oracle CRM On Demand.
    
  • Salesforce.
    
  • SFTP. Secure FTP.
    
  • SAP_ALE_IDoc_Reader. SAP IDoc Reader.
    
  • SAP_ALE_IDoc_Writer. SAP IDoc Writer.
    
  • SqlServer. Microsoft SQL Server 2000.
    
  • SqlServer2005. Microsoft SQL Server 2005.
    
  • SqlServer2008. Microsoft SQL Server 2008.
    
  • SqlServer2012. Microsoft SQL Server 2012.
    
  • SqlServer2014. Microsoft SQL Server 2014.
    
  • SqlServer2016. Microsoft SQL Server 2016.
    
  • TOOLKIT. Informatica Cloud Connector.
    
  • WebServicesConsumer. Web Service. 
    

NOTE:
The user interface field name on the Connections page varies depending on the connection. For example, for SQL Server, the user interface field name is SQL Server Version. Also note that for SQL Server, the REST API attribute that populates the value in the user interface is named subType.

port

Int

Port number for FTP/SFTP, Microsoft SQL Server, MySQL, and Oracle connections.

password

String

Password for the connection.

username

String

User name for the connection.

securityToken

String

Security token for a Salesforce connection.

stsUrl

String

Security token service URL for Microsoft Dynamics CRM connections that use Active Directory authentication.

organizationName

String

Organization name for Microsoft Dynamics CRM connections.

timeout

Int

Timeout for Web Service connections.

trustCertificatesFile

String

Trust certificates file name for Web Service connections.

certificateFile

String

Certificates file name for Web Service connections.

certificateFilePassword

String

Certificates file password for Web Service connections.

certificateFileType

String

Certificates file type for Web Service connections.

privateKeyFile

String

Private key file name for Web Service connections.

privateKeyPassword

String

Private key password for Web Service connections.

privateKeyFileType

String

Private key file type for Web Service connections.

connParams

String

Parameters used in the connection.
Includes connection attributes in the connParam object for SAP, NetSuite, Oracle CRM On Demand, and Informatica Cloud Connector connections.

connListItem

List of connections included in the connListItem object.

id

String

Included in the connListItem object.
Source or target ID.

name

String

Included in the connListItem object.
Source or target name.

Test GET Request

To test a connection, use the connection ID in the following URI:

/api/v2/connection/test/<id>

Test GET Response

Returns the success object if the test succeeds.
Returns the error object if errors occur.

POST Request

You can create or update connections. To update a connection, use the connection ID with the following URI. To create a connection, omit the optional connection ID.

/api/v2/connection/<id>

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

Update-Mode=PARTIAL

In a connection POST request, use the additional attributes in the connection object. The attributes used by Informatica Cloud Connector connections vary by connection type.
To create or update an Informatica Cloud Connector connection, consult the Informatica Cloud application for the attributes used by the connection. Enclose any attributes that are not listed in the following tables in a connParam object.
To get a list of connectors that are available to the organization and attribute information for a specific connector type, see connector.
For more information about attributes and data types used for creating connections through the REST API, see Connection user interface fields to REST API attributes mapping and Connector data types.

POST Response

If successful, returns the connection object for the connection that was created or updated.
Returns the error object if errors occur.

DELETE Request

To delete a connection, use the connection ID in the following URI

/api/v2/connection/<id>

DELETE Response

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

POST Example

To update an SAP Table connection, you might use the following request, enclosing SAP attributes in the connParam object:

POST <serverUrl>/api/v2/connection/0002D420000000J
Content-Type: application/xml
Accept: application/xml
icSessionId: <icSessionId>

<connection>
  <id>0002D420000000J</id>
  <orgId>00342000</orgId>
  <name>test dir</name>
  <type>TOOLKIT</type>
  <agentId>00001Y08000000000002</agentId>
  <username>username</username>
  <password>password</password>
  <instanceName>SAPTableConnector</instanceName>
  <connParams>
     <agentId>00001Y08000000000002</agentId>
     <username>username</username>
     <password>password</password>
     <client>800</client>
     <language>EN</language>
     <Saprfc Ini Path>C:\\Windows\\SysWOW64</Saprfc Ini Path>
     <Destination>GE6</Destination>
  </connParams>
  <runtimeEnvironmentId>00000C25000000000002</runtimeEnvironmentId>
</connection>

A successful request returns the connection object that you updated.