REST API Reference

Back Next

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:

win64

linux64

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: