REST API Reference > Platform REST API version 2 resources > Secure Agents and services
  

Secure Agents and services

Use this resource to receive an install token to register a Secure Agent, download the checksum of the agent installation program, request the details about Informatica Cloud Secure Agents or Secure Agent services, or delete a Secure Agent.

GET request for Secure Agent install token and checksum

To request an install token so that you can complete the Secure Agent registration process or to get the checksum of the agent installation program, include the platform type in the URI as follows:
/api/v2/agent/installerInfo/<platform>
Use one of the following values for the platform:

GET response for Secure Agent install token and checksum

A successful request returns the download URL, install token, and checksum download URL, as shown in the following sample response:
{
"@type": "agentInstallerInfo",
"downloadUrl": "https://pdm.ics.dev/package-manager/files/binary/agent64_install_ng_ext/6403/win64/agent64_install_ng_ext.6403.exe",
"installToken": "PJ7NVrQ0SGpnpbmJ8K5yte18HLDw305DwPgP_jxG1R4KiOY9BL6qxV7jWiv7wSEfg7mQHKRWX6kcEVph1xjswX",
"checksumDownloadUrl": "https://pdm.ics.dev/package-manager/files/binary/agent64_install_ng_ext/6403/win64/agent64_install_ng_ext.6403_win64.sha256"
}
To verify the checksum on Windows, use a third-party utility, for example, HashMyFiles or 7-Zip, to find the checksum for the Secure Agent installation program and compare it to the checksum in the checksum.txt file. The hashing algorithm is CRC-32.
To verify the checksum on Linux, run the command cksum <Secure Agent installer filename> and compare the checksum to the checksum in the checksum.txt file. The first column of the command output is the checksum.

GET request for agent details

You can request the details about Secure Agents or details about the services that run on Secure Agents.
Secure Agent details
To request the details about all Secure Agents in the organization, use the following URI:
/api/v2/agent
To request a list of all the Secure Agents that are currently not assigned to any group, use the following URI:
/api/v2/agent/?includeUnassignedOnly=true
To request the details about a particular Secure Agent, you can include the Secure Agent ID or the Secure Agent name in the URI. Use one of the following URIs:
/api/v2/agent/<agent ID>
/api/v2/agent/name/<name>
If you use the Secure Agent name in the request and the Secure Agent name includes a space, replace the space with %20. For example:
/api/v2/agent/name/special%20agent
Secure Agent services status and details
To request the status of services that run on all of the Secure Agents in the organization, use the following URI:
/api/v2/agent/details
To request the status of services that run on a particular Secure Agent, include the agent ID in the URI as follows:
/api/v2/agent/details/<agent ID>
If you want the response to include Secure Agent details in addition to the status, include the following parameter in the request: ?onlyStatus=false. For example, the following request returns the agentEngineStatus and agentEngineConfigs objects for a specified Secure Agent:
/api/v2/agent/details/<agent ID>?onlyStatus=false

GET response for agent details

Returns the agent object for the requested Secure Agent ID or Secure Agent name.
If you request information for all Secure Agents in the organization, returns an agent object for each Secure Agent in the organization.
If you request details for agent services, returns an AgentEngine object in addition to the agent object.
Returns the error object if errors occur.
The agent object includes the following attributes:
Field
Type
Description
id
String
Secure Agent ID.
orgId
String
Organization ID.
name
String
Secure Agent name.
description
String
Description of the Secure Agent.
createTime
Date/time
Time the Secure Agent was created.
updateTime
Date/time
Last time the Secure Agent was updated.
createdBy
String
User who created the Secure Agent.
updatedBy
String
User who updated the Secure Agent.
active
Boolean
Whether the Secure Agent is active. Returns true or false.
readyToRun
Boolean
Whether the Secure Agent is ready to run a task. Returns true or false.
platform
String
Platform of the Secure Agent machine. Returns one of the following values:
  • - win64
  • - linux64
agentHost
String
Host name of the Secure Agent machine.
proxyHost
String
Host name of the outgoing proxy server that the Secure Agent uses.
proxyPort
Int
Port number of the outgoing proxy server.
proxyUser
String
User name to connect to the outgoing proxy server.
agentVersion
String
Secure Agent version.
spiUrl
String
This field is no longer applicable and has been deprecated.
upgradeStatus
String
Upgrade status.
lastUpgraded
Date/time
Last time the Secure Agent was upgraded.
lastUpgradeCheck
Date/time
Last time the Secure Agent was checked for upgrade.
lastStatusChange
Date/time
Last time the Secure Agent status was updated.
packages
String
This field is no longer applicable and has been deprecated.
configUpdateTime
Date/time
Last time a user updated Secure Agent properties.
agentGroupId
String
ID of the Secure Agent group.
agentConfigs
This object is no longer applicable and has been deprecated.
name
String
Included in the agentConfig object.
Deprecated.
type
String
Included in the agentConfig object.
Deprecated.
subtype
String
Included in the agentConfig object.
Deprecated.
value
String
Included in the agentConfig object.
Deprecated.
customized
Boolean
Included in the agentConfig object.
Deprecated.
overridden
Boolean
Included in the agentConfig object.
Deprecated.
defaultValue
String
Included in the agentConfig object.
Deprecated.
platform
String
Included in the agentConfig object.
Deprecated.
If you request details for the services that run on Secure Agents, the agent object also includes the AgentEngine object. The AgentEngine object includes the following attributes:
Field
Type
Description
agentEngineStatus
Status of the agent service, which includes information in the AgentEngineStatus object.
appname
String
Included in the AgentEngineStatus object.
The service name that is used internally.
appDisplayName
String
Included in the AgentEngineStatus object.
The service name that displays in the user interface.
appversion
String
Included in the AgentEngineStatus object.
The service version. The version number changes each time you modify the service.
replacePolicy
-
Used for internal purposes only.
status
String
Included in the AgentEngineStatus object.
The status of the service. Possible values include:
  • - RUNNING. The service is running and ready to accept jobs.
  • - DEPLOYING: The service is being provisioned.
  • - STOPPED. The service has been stopped.
  • - ERROR. The service is in an error state.
  • - NEED_RUNNING. The start process is set to begin or has started.
  • - NEED_STOP. The stop process is set to begin or has started.
desiredStatus
-
Used for internal purposes only.
subState
String
Included in the AgentEngineStatus object.
A value of 0 indicates that the service is operational. All other values indicate that the service is not operational.
createTime
Date/time
Included in the AgentEngineStatus object.
The time the service was created.
updateTime
Date/time
Included in the AgentEngineStatus object.
The last time the service was updated.
agentEngineConfigs
Defines agent service properties. Includes information in an engineConfig object for each agent service property.
Included when the request includes the parameter statusOnly=false.
type
String
Included in the engineConfig object.
Configuration type.
name
String
Included in the engineConfig object.
Configuration property name.
value
String
Included in the engineConfig object.
Value of the property.
platform
String
Included in the engineConfig object.
Platform. Returns one of the following values:
  • - win64
  • - linux64
customized
Boolean
Included in the engineConfig object.
Whether the property is in the custom configuration details. Returns true or false.
A successful response might look similar to the follow example:

GET details example

To request the details about the Secure Agent with an ID of 10044030000000000GC, to be returned in JSON format, you might use the following request:
GET <serverUrl>/api/v2/agent/10044030000000000GC
Accept:application/json
icSessionId: <icSessionId>
The following example shows a successful response:
{
"@type": "agent",
"id": "10044030000000000GC",
"orgId": "010025",
"name": "MyAgent",
"createTime": "2021-02-25T00:42:39:000Z",
"updateTime": "2021-02-25T00:42:39:000Z",
"createdBy": "larry104",
"updatedBy": "larry104",
"active": "false",
"readyToRun": "false",
"platform": "linux64",
"agentHost": "agentHost5",
"serverUrl": "https://na4.dm-us.informaticacloud.com/saas",
"proxyPort": "0",
"upgradeStatus": "NotUpgrading",
"federatedId": "6iPQuOsH1YAfnJvhZWPZjI",
"createTimeUTC": "2021-02-25T00:42:39:000Z",
"updateTimeUTC": "2021-02-25T00:42:39:000Z",
"agentGroupId": "01000125000000000002"
}

DELETE request

You can delete a Secure Agent if it is not associated with any connections. Before you delete a Secure Agent, update associated connections to use another Secure Agent.
To delete a Secure Agent, use the Secure Agent ID in the following URI:
/api/v2/agent/<id>

DELETE response

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