REST API Reference > Platform REST API version 2 resources > Runtime environments
  

Runtime environments

You can use the runtimeEnvironment resource to request runtime environment details and manage Secure Agent groups.
You can perform the following tasks using the REST API:

Getting runtime environment details

Use the runtimeEnvironment resource to get runtime environment details.
You can request the details for a specific runtime environment or details for all of an organization's runtime environments,
To request runtime environment information for an organization, use the following URI:
/api/v2/runtimeEnvironment
To request the details of a particular runtime environment, you can include the runtime environment ID or name in the URI. Use one of the following URIs:
/api/v2/runtimeEnvironment/<id>
/api/v2/runtimeEnvironment/name/<name>
If you use the runtime environment name in the URI and the runtime environment name includes a space, replace the space with %20. For example:
/api/v2/runtimeEnvironment/name/my%20runtime%20environment

GET Response

Returns runtime environment information for the requested runtime environment. The runtimeEnvironment object includes the following attributes:
Field
Type
Description
id
String
Runtime environment ID.
orgId
String
Organization ID.
name
String
Runtime environment name.
description
String
Description of the runtime environment.
createTime
Date/time
Date and time the runtime environment was created.
updateTime
Date/time
Date and time that the runtime environment was last updated.
createdBy
String
User who created the runtime environment.
updatedBy
String
User who last updated the runtime environment.
agents
Agents assigned to the runtime environment. See the agent resource.
isShared
Boolean
Indicates whether the Secure Agent group is shared. Returns one of the following values:
  • - true. The Secure Agent group is shared.
  • - false. The Secure Agent group is not shared.
federatedId
String
Global unique identifier.
serverlessConfig
Attribute that defines serverless runtime environment properties.
If you get information about a serverless runtime environment, the runtimeEnvironment object also includes the serverlessConfig object. The serverlessConfig object includes the following attributes:
Field
Type
Description
platform
String
Cloud platform that hosts the serverless runtime environment.
applicationType
String
Application that can use the serverless runtime environment.
status
String
Status of the serverless runtime environment.
statusMessage
String
Status message for the serverless runtime environment.
statusMessageDetails
String
Validation error data from AWS for the serverless runtime environment.
cloudProviderConfig
Defines basic properties and Data Integration properties.
infaAccountNumber
String
Included in the cloudProviderConfig object.
Informatica's account number on the cloud platform.
externalId
String
Included in the cloudProviderConfig object.
External ID to associate with the role.
configurationName
String
Included in the cloudProviderConfig object.
Name of the serverless runtime environment.
configurationDescription
String
Included in the cloudProviderConfig object.
Description of the serverless runtime environment.
params
Defines the AWS resource configuration properties.
s3
String
Included in the params object.
Location on Amazon S3 to store supplementary files.
subnet
String
Included in the params object.
ID of the subnet.
role
String
Included in the params object.
Name of the role that the serverless runtime environment assumes.
vpc
String
Included in the params object.
ID of the VPC (Amazon Virtual Private Cloud).
externalId
String
Included in the params object.
External ID that is configured for the role.
securityGroup
String
Included in the params object.
Security group ID.
accountNumber
String
Included in the params object.
Your account number on the cloud platform.
referenceId
String
Included in the params object.
Internal ID used to reference the serverless runtime environment.
computeUnits
String
Included in the params object.
Maximum number of serverless compute units that a task can use.
executionTimeout
String
Included in the params object.
Amount of time in minutes to wait for a task to complete.
cloudInstanceId
String
Included in the params object.
Instance ID.
zone
String
Included in the params object.
Availability zone ID.
region
String
Included in the params object.
Region on the cloud platform.
infaAccountNumber
String
Included in the params object.
Informatica's account number on the cloud platform.
awsTags
String
Included in the params object.
AWS tags.
maxComputeUnits
String
Maximum number of serverless compute units that a task can use.
executionTimeout
String
Amount of time in minutes to wait for a task to complete.

Get Example

To request the details of a particular runtime environment, you might use the following request:
GET <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004
Accept:application/json
icSessionId: <icSessionId>
The following text is a sample return in JSON:
{
"@type": "runtimeEnvironment",
"id": "00000425000000000004",
"orgId": "000004",
"name": "SUT_Agent",
"createTime": "2016-12-09T12:34:01.000Z",
"updateTime": "2016-12-09T17:54:00.000Z",
"createdBy": "org1@infa.com",
"updatedBy": "org1@infa.com",
"agents": [],
"isShared": true,
"federatedId": "6iPQuOsH1YAfnJxhZWPZjI"
}
The following text is a sample return for a serverless runtime environment:
{
"@type": "runtimeEnvironment",
"id": "01000000000000000039",
"orgId": "010211",
"name": "Serverless runtime environment 1",
"description": "My serverless runtime environment",
"createTime": "2020-08-25T13:21:16.000Z",
"updateTime": "2020-08-25T13:29:43.000Z",
"createdBy": "admin",
"updatedBy": "admin",
"agents": [],
"isShared": false,
"federatedId": "4sddtYsgbpnpTBjSZB12fs",
"serverlessConfig": {
"platform": "AWS",
"applicationType": "CDI",
"status": "RUNNING",
"statusMessage": "Serverless runtime is running",
"cloudProviderConfig": {
"cloudConfig": [
{
"infaAccountNumber": "064942996470",
"externalId": "7eeafa7c-6dd1-4666-8ac8-7431b1d72def",
"configurationName": "Serverless runtime environment 1",
"configurationDescription": "My serverless runtime environment",
"params": {
"s3": "s3://discale-qa-west2/test1",
"subnet": "subnet-08123adayy51ed327",
"role": "CDI_Serverless_Role",
"vpc": "vpc-02ef05yy73fb7f063",
"externalId": "7eeafa7c-6dd1-4666-8ac8-7431b1d72def",
"securityGroup": "sg-025d67343b0655372",
"accountNumber": "778525666549",
"referenceId": "4sddtYsgbpnpTBjSZB12fs",
"computeUnits": "1",
"executionTimeout": "2880",
"cloudInstanceId": "i-0e3e6g02r1g1364a3",
"zone": "usw2-az3",
"region": "us-west-2",
"infaAccountNumber": "064942996470",
"awsTags": "Key=NAME,Value=test1 Key=EMAIL,Value=test1@informatica.com"
}
}
]
},
"maxComputeUnits": "1",
"executionTimeout": "2880"
}

Creating, updating, and deleting Secure Agent groups

You can use the runtimeEnvironment resource to create, update, and delete Secure Agent groups.
Use a POST request to create and update Secure Agent groups. Use a DELETE request to delete a Secure Agent group.

POST request

To create a Secure Agent group, use the following URI:
/api/v2/runtimeEnvironment
Include the following fields in the request:
Field
Type
Required
Description
name
String
Yes
Name of the Secure Agent group.
isShared
Boolean
-
Whether the Secure Agent group can be shared with sub-organizations.
To update a Secure Agent group, include the agent group ID as shown in the following URI:
/api/v2/runtimeEnvironment/<id>
You can add or remove agents and rename Secure Agent groups. To move an agent from one Secure Agent group to another group, send a request to remove the agent from its current group and then send a request to add the agent to the new group.
Include the following fields in the request:
Field
Type
Required
Description
name
String
Yes
Name of the Secure Agent group.
isShared
Boolean
-
Whether the Secure Agent group can be shared with sub-organizations.
agents
Array
Yes
Agents assigned to the Secure Agent group.
orgId
String
Yes
Organization ID.
id
String
Yes
Agent ID.

POST response

Field
Type
Description
id
String
Secure Agent group ID.
orgId
String
Organization ID.
name
String
Secure Agent group name.
description
String
Description of the Secure Agent group.
createTime
Date/time
Date and time the Secure Agent group was created.
updateTime
Date/time
Date and time that the Secure Agent group was last updated.
createdBy
String
User who created the Secure Agent group.
updatedBy
String
User who last updated the Secure Agent group.
agents
Array
Agents assigned to the Secure Agent group. For more information, see the agent resource.
isShared
Boolean
Indicates whether the Secure Agent group is shared. Returns one of the following values:
  • - true. The Secure Agent group is shared.
  • - false. The Secure Agent group is not shared.
federatedId
String
Global unique identifier.
serverlessConfig
Attribute that defines serverless runtime environment properties.

POST request examples

The following example shows a request to create a Secure Agent group:
POST <serverUrl>/api/v2/runtimeEnvironment
Accept:application/json
icSessionId: <icSessionId>
{
"@type": "runtimeEnvironment",
"name": "14402",
"isShared": true
}
The following example shows a request to add an agent to a Secure Agent group:
POST <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004
Accept:application/json
icSessionId: <icSessionId>
{
"@type": "runtimeEnvironment",
"name": "14401",
"agents": [
{
"@type": "agent",
"id": "01000308000000000003",
"orgId": "010003"
}
],
"isShared": false
}

POST response example

You might receive a response similar to the following example:
{
"@type": "runtimeEnvironment",
"id": "01000325000000000005",
"orgId": "010003",
"name": "USW1MJ02W6PP-2",
"createTime": "2021-11-09T17:20:55.583Z",
"updateTime": "2021-11-09T17:20:55.583Z",
"createdBy": "ctan",
"updatedBy": "ctan",
"agents": [],
"isShared": false,
"federatedId": "9F4z0pY1kKqdlmLp5kYXkF",
"createTimeUTC": "2021-11-09T22:20:55.583Z",
"updateTimeUTC": "2021-11-09T22:20:55.583Z",
"serverlessConfig": {
"cloudProviderConfig": {
"cloudConfig": []
}
}
}

DELETE request

To delete a Secure Agent group, include the agent group ID as shown in the following URI:
/api/v2/runtimeEnvironment/00000425000000000034

Managing Secure Agent group selections

You can use the runtimeEnvironment resource to enable or disable Informatica Intelligent Cloud Services and connectors for a Secure Agent group. You can also get details about the selections.
Use a GET request to get the details about a Secure Agent group's enabled and disabled selections. Use a PUT request to assign a Secure Agent group to services and connectors.

GET request

You can request information about the selections that are enabled for a Secure Agent group. You can also request information about all of the selections that are available for a Secure Agent group based on the organization's license. The response includes the names and IDs of the available services and connectors.
To get information about enabled selections, use the following URI:
/api/v2/runtimeEnvironment/<id>/selections
To get information about all of the selections that are available to a Secure Agent group, use the following URI:
/api/v2/runtimeEnvironment/<id>/selections/details

GET response

Returns the Secure Agent group selections. If successful, returns the following fields:
Field
Type
Description
services
Contains selection information for services.
selections
Contains information for enabled services.
If the request is to include details, also contains selection information for disabled services.
id
String
Included in the selections object.
Service ID.
name
String
Included in the selections object.
Service name.
enabled
Boolean
Included in the selections object.
Whether the service is enabled for the Secure Agent group.
connectors
Contains selection information for connectors.
selections
Contains information for enabled connectors.
If the request is to include details, also contains selection information for disabled connectors.
id
String
Included in the selections object.
Connector ID.
name
String
Included in the selections object.
Connector name.
enabled
Boolean
Included in the selections object.
Whether the connector is enabled for the Secure Agent group.
Additional services
Contains selection information for additional services, for example, Git.
selections
Contains information for additional services that are enabled.
If the request is to include details, also contains selection information for additional services that are disabled.
id
String
Included in the selections object.
Service ID.
name
String
Included in the selections object.
Service name.
enabled
Boolean
Included in the selections object.
Whether the service is enabled for the Secure Agent group.

GET request example

The following example shows a request to get information about enabled selections:
POST <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004/selections
Accept:application/json
icSessionId: <icSessionId>
The following example shows a request to get information about enabled and disabled selections:
POST <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004/selections/details
Accept:application/json
icSessionId: <icSessionId>

GET response example

If the request is for enabled and disabled selections, you might receive a response similar to the following example:
{
"services": {
"selections": [
{
"id": "00000047000000000002",
"name": "Data Integration",
"enabled": true
}
]
},
"connectors": {
"selections": [
{
"id": "01000000000005L",
"name": "Amazon Redshift v2",
"enabled": true
},

{
"id": "01000000000005Q",
"name": "Amazon S3",
"enabled": false
}
]
},
"additionalServices": {
"selections": [
{
"id": "00000048000000000002",
"name": "Git",
"enabled": false
}
]
}
}

PUT request

To enable services and connectors for a Secure Agent group, include the agent group ID as shown in the following URI:
/api/v2/runtimeEnvironment/<id>/selections
To see a list of all of the services and connectors that are available and find the selection IDs, use a GET request to obtain information about enabled and disabled selections.
Include the following fields in the request:
Field
Type
Required
Description
id
String
Yes
The selection object ID.
name
String
-
The selection object name.
enabled
Boolean
-
Whether to enable or disable the selection.

PUT request example

If you want to select the Data Integration service, the Amazon Redshift v2 connector, and the Git service for a Secure Agent group, the request might be similar to the following example:
Note: The IDs shown in the example are examples only. Use a GET request to find the selection IDs and names that are available to the Secure Agent group.
PUT <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004/selections
Accept:application/json
icSessionId: <icSessionId>
{
"services": {
"selections": [
{
"id": "00000047000000000002",
"name": "Data Integration",
"enabled": true
}
]
},
"connectors": {
"selections": [
{
"id": "01000000000005L",
"name": "Amazon Redshift v2",
"enabled": false
},
{
"id": "01000000000005M",
"name": "Amazon S3 v2",
"enabled": false
}
]
},
"additionalServices": {
"selections": [
{
"id": "00000047000000000013",
"name": "Self-hosted Git Repo",
"enabled": true
}
]
}
}

Configuring Secure Agent service properties for Secure Agent groups

You can use the runtimeEnvironment resource to configure Secure Agent service properties for a Secure Agent group. When you add a Secure Agent to the Secure Agent group, the agent uses the group-level property settings by default instead of using the Secure Agent service default settings.
The Secure Agent service properties that you can configure for a Secure Agent group depend on which services and connectors are assigned to the group. To see the editable properties for a particular Secure Agent group, you can send a GET request for configuration details.
The following rules apply when you configure Secure Agent service properties for a Secure Agent group:
Warning: Do not configure agent-level Secure Agent service property settings for an agent in a Secure Agent group that uses group-level property settings. If you want to configure agent-level property settings, delete the group-level property settings before you configure the agent properties.

GET request

Use a GET request to get a list of editable Secure Agent service properties that you can configure for a Secure Agent group.
You can also get a list of group-level properties that have overridden Secure Agent service default property settings.
Include the Secure Agent group ID in the URI. Optionally, include the platform in the URI. You can use linux64 or win64. The default platform is linux64.
Use one of the following URIs:

GET response

A successful response returns the Secure Agent services, property types, and the following fields in the property type object:
Field
Type
Description
name
String
Property name.
value
String
Value used for all agents added to the Secure Agent group.
isCustom
Boolean
Whether the property is a custom property.
isSensitive
Boolean
Whether the property value is sensitive data that is masked.

GET response example

If you request the properties that have overridden the Secure Agent service default property settings, you might receive a response similar to the following example:
{
"Data_Integration_Server": [
{
"TOMCAT_CFG": [
{
"name": "MySQL_JDBC_DRIVER_JARNAME",
"value": "mysql-connector-java-8.0.13.jar"
},
{
"name": "NetworkTimeoutPeriod",
"value": "335"
}
]
},
{
"PMRDTM_CFG": [
{
"name": "SalesforceConnectionTimeout",
"value": "311"
},
{
"name": "customConfig-DTM-DIX-linux",
"value": "custom-new",
"isCustom": "true"
}
]
}
]
}

PUT request

Use to configure Secure Agent service properties for a Secure Agent group. The properties that you configure will override the default property settings for the specified Secure Agent service. Include the Secure Agent group ID in the URI.
Optionally, include the platform in the URI. You can use linux64 or win64. The default platform is linux64.
Use the following URI:
/api/v2/runtimeEnvironment/<id>/configs/<platform>
In the body of the request, include the Secure Agent service name, the property type, and a name/value pair for the property, for example:
{
"<Secure Agent service name>": [
{
"<Property type 1>": [
{
"name": "<property name>",
"value": "<property value>"
},
{
"name": "<property name>",
"value": "<property value>"
}
]
},
{
"<Property type 2>": [
{
"name": "<property name>",
"value": "<property value>"
},
{
"name": "<property name>",
"value": "<property value>"
}
]
}
]
}
Use the service and property names as shown in a GET response. For example, for the Data Integration Server service, use Data_Integration_Server.
The properties that you don't include in the request will retain their existing settings.
Include the following fields in the property type object:
Field
Type
Required
Description
name
String
Yes
Property name.
value
String
Yes
Value to use for all agents added to the Secure Agent group.
To use the system default value, use APP_DEFAULT.
isCustom
Boolean
-
Whether the property is a custom property.
Default is False.
isSensitive
Boolean
-
Whether the property value is sensitive data that you want to mask.
Default is False.
Returns a success code if successful or errors if unsuccessful.

PUT request example

If you want to configure the TOMCAT_CFG property type for the Data Integration Server service, the request might be similar to the following example:
PUT <serverUrl>/api/v2/runtimeEnvironment/00000425000000000004/configs
Accept:application/json
icSessionId: <icSessionId>
{
"Data_Integration_Server": [
{
"TOMCAT_CFG": [
{
"name": "MySQL_JDBC_DRIVER_JARNAME",
"value": "mysql-connector-java-8.0.14.jar"
},
{
"name": "customConfig-Tomcat-DIS-linux",
"value": "custom-new",
"isCustom": "true"
}
]
}
]
}

DELETE request

You can delete Secure Agent service property settings that were configured for a Secure Agent group. When you delete the group-level properties, the settings for all of the Secure Agents in the group change to the Secure Agent service default settings. Custom properties that were created for the Secure Agent group are removed.
To delete the property settings for a Secure Agent group, include the Secure Agent group ID in the following URI:
/api/v2/runtimeEnvironment/<id>/configs
Returns a success code if successful or errors if unsuccessful.