You can use the REST API to run, stop, and monitor taskflows directly on a Customer Managed Secure Agent group, without routing the request through IDMC. Use these APIs to get taskflow status when the agent group is disconnected from IDMC.
Taskflows REST API resources send requests to the IDMC URL. However, the Customer Managed Secure Agent group REST API sends requests directly to the Secure Agent in the agent group.
Use the Customer Managed Secure Agent group REST API to perform the following tasks:
•Authenticate API requests
•Run a taskflow
•Stop a taskflow instance
•Resume a suspended taskflow
•Restart a taskflow
•Monitor taskflow status
For information about creating and configuring a Customer Managed Secure Agent group, see the Administrator help.
Authenticating API requests to a Customer Managed Secure Agent group
To call the taskflow REST API resources on a Customer Managed Secure Agent group, authenticate with the Secure Agent and get a JSON web token (JWT). Include this token in the Authorization header of each subsequent request.
Authenticate with a separate password that you set for API and command line access. This password is distinct from your IDMC password and never confirms your identity against IDMC. The Secure Agent validates this password locally, so authentication works even when the agent group is disconnected from IDMC.
For more information, see Rest API Reference and Runtime Environments in the Administrator help.
POST request
To get a JWT, use the following URI:
POST https://<Secure Agent host>:<port>/rm/api/v2/login Content-Type: application/json
JWT to include in the RM-USER-TOKEN header of subsequent requests.
expiresIn
Integer
Number of seconds until the token expires.
Note:
By default, the token expires after 15 minutes. You can request for a new token before the current one expires. There's no session renewal endpoint. Hence, you need to call this resource again to generate a new token.
Running a taskflow on a Customer Managed Secure Agent group
Use the REST API to run a taskflow directly on a Customer Managed Secure Agent group. Use this resource to trigger taskflows from a third-party scheduler or an orchestration tool without an IDMC connection.
Before you run a taskflow on a Customer Managed Secure Agent group, verify the following prerequisites:
•You deployed the taskflow to the Customer Managed Secure Agent group, and the taskflow and its assets are synchronized and activated.
•You obtained a JWT.
POST request
To run a taskflow, use the following URI:
POST https://<Secure Agent host>:<port>/rm/api/v2/job RM-USER-TOKEN: <token> Content-Type: application/json
To stop a running taskflow, use the following URI:
PUT https://<Secure Agent host>:<port>/rm/active-bpel/restadmin/processes/<run ID>/terminate?isManual=true RM-USER-TOKEN: <token>
The request body contains the following fields:
Parameter
Type
Description
<run ID>
Number
The ID of the taskflow run to stop.
isManual
Boolean
Required. Set to true.
PUT response
The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. If the request fails, the response contains the same error information as the corresponding Data Integration resource.
Resuming a suspended taskflow run on a Customer Managed Secure Agent group
Use the REST API to resume a taskflow run that is suspended on a Customer Managed Secure Agent group.
To resume a suspended taskflow run, use the following URI:
PUT https://<Secure Agent host>:<port>/rm/active-bpel/restadmin/processes/<run ID>/resume RM-USER-TOKEN: <token>
In the URI, <run ID> is the ID of the taskflow run to resume.
PUT response
The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. The run status changes from Suspended to Running.
If the run isn't suspended, the request has no effect on the run.
Restarting a taskflow run on a Customer Managed Secure Agent group
Use the REST API to restart a taskflow run on a Customer Managed Secure Agent group. The agent starts a new run of the taskflow. The original run doesn't change.
You can restart a suspended taskflow instance but not a taskflow instance that's still running.
POST request
To restart a taskflow run, use the following URI:
POST https://<Secure Agent host>:<port>/rm/active-bpel/restadmin/processes/<run ID>/restartasnew RM-USER-TOKEN: <token>
In the URI, <run ID> is the ID of the taskflow instance to restart.
POST response
The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. The response doesn't include the run ID of the new run. To find the new run, use the status resource. For more information, see Monitoring taskflow status on a Customer Managed Secure Agent group.
If the original run is still running, the request fails with the same error that Data Integration returns.
Monitoring taskflow status on a Customer Managed Secure Agent group
Use the status resource to monitor a taskflow running on a Customer Managed Secure Agent group. The request and response match those for the status resource described in Monitoring taskflow status with the status resource. The only difference is that you send the request directly to the agent, not to your IDMC URL.
GET request for a single run
To get the status of one taskflow run, use the following URI:
GET https://<Secure Agent host>:<port>/rm/active-bpel/services/tf/status/<run ID> RM-USER-TOKEN: <token>
To include details about each subtask, add ?subtaskDetails=yes to the URI.
You can include the following optional headers. The headers apply only to requests for a single run.
Header
Description
Max-Retry
Number of times the agent retries the lookup if it doesn't find the run. Maximum value is 5.
Retry-Interval
Number of seconds between retries. Maximum value is 20.
Query this resource directly on the agent to get real-time status when the agent group is disconnected from IDMC. Taskflow runs that start while the agent group is disconnected don't appear in Monitor until the agent group reconnects and synchronizes run history. Synchronization time depends on the number of runs that occurred during the disconnection.
You can't perform live job actions, such as stop or restart, against runs from Monitor in IDMC while the agent group is disconnected. To stop a run while disconnected, use the agent-side stop resource. For more information, see Stopping a taskflow run on a Customer Managed Secure Agent group.
GET request for suspended runs
To list the taskflow runs that are suspended, use the following URI:
GET https://<Secure Agent host>:<port>/rm/active-bpel/services/tf/status?runStatus=Suspended RM-USER-TOKEN: <token>
You can also use the startTime, endTime, offset, rowLimit, and subtaskDetails query parameters. These parameters work the same way as they do in Monitoring taskflow status with the status resource. The rowLimit value can range from 10 through 50.
A run doesn't appear in this list after you resume it or stop it.
GET response
A request for a single run returns one status object. A request for suspended runs returns an array of status objects. If no run matches, the response is HTTP status code 200 with the following body:
{ "status": "No status available" }
The agent returns the HTTP status code 400 if the run ID isn't valid, and 500 if the agent can't read the run data. The response body contains the reason, code, detail, and message fields.
Rules and Guidelines
Consider the following rules and guidelines when you monitor taskflow runs on a Customer Managed Secure Agent group:
•Monitor shows limited information about taskflow runs on a Customer Managed Secure Agent group. To check run status, use the status resource.
•The agent deletes run data after 30 days. To keep the data, query or export it before then.