POST Orchestrator Jobs Custom

The POST /OrchestratorJobs/Custom operation schedules a job with a custom job type on an orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores.. On success, the operation returns HTTP 200 OK with  the GUID for the scheduled job.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/agents/management/modify/

Tip:  Data returned from a custom job once the job completes is stored in the Keyfactor Command database. To retrieve the data, use the GET Orchestrator Jobs Job History operation to determine the JobHistoryId of the completed job and then use the GET Orchestrator Jobs Job Status Data operation to retrieve the data.

Version 2 of POST /OrchestratorJobs/Custom adds support for pooled orchestrators.

Note:  Like other pooled orchestrator jobs, a Fetch Logs job is assigned to an available orchestrator in the selected orchestrator pool. If you need logs from a specific orchestrator, create or select a pool that contains only that orchestrator. This ensures that the intended orchestrator accepts and processes the job.

Table 621: POST Orchestrator Jobs Custom Input Parameters V2

Name In Description
JobFields Body

An object that set the values for any optional job fields configured for the custom job type. The key is the field name and the value is the value for the field.

For example:

Copy 
"JobFields": {
   "Favorite Type of Pet": "Rat",
   "Mother's Birthday": "1952-05-21"
}
Note:  If a job field has been configured with a default value and you wish to accept the default value, the field does not need to be submitted along with the POST /OrchestratorJobs/Custom request. The default value will be set automatically by Keyfactor Command. Submitting a value overrides the default value.

Use the GET Custom Job Types operation to retrieve a list of your defined custom job types to determine the job fields defined for the job type.

Tip:  The built-in Fetch Logs job does not have any optional job fields.
JobTypeName Body

Required. A string indicating the reference name for the custom job type for the job.

Use the GET Custom Job Types operation to retrieve a list of your defined custom job types to determine the job type name to use.
OrchestratorPoolId Body

Required. A string indicating the Keyfactor Command reference GUID of the orchestrator pool for this custom job.

Use the GET Orchestrator Pools operation with a query of Capability -includes "Custom" to retrieve a list of your orchestrator pools with the this capability to determine the ID of the orchestrator pool to use for the request.
Schedule Body

An object containing the schedule for the custom job. ClosedShow schedule details.

The default is Immediate.

Table 622: POST Orchestrator Jobs Custom Response Data V2

Name Description
JobFields

An array of objects that set the values for any optional job fields configured for the custom job type.
JobId A string indicating the Keyfactor Command reference GUID for the job.
JobTypeName

A string indicating the reference name for the custom job type for the job.
OrchestratorPoolId

A string indicating the Keyfactor Command reference GUID of the orchestrator pool that will execute this job.
RequestTimestmap A string containing the date, in UTC, when the custom job was submitted.
Schedule

An object containing the schedule for the custom job.

Use version 1 of POST /OrchestratorJobs/Custom only with orchestrators that do not support high availability. Version 1 provides functionality similar to version 2, but it does not support assigning custom jobs to an orchestrator pool.

Table 623: POST Orchestrator Jobs Custom Input Parameters V1

Name In Description
AgentId Body

Required. A string indicating the Keyfactor Command reference GUID of the orchestrator that will execute this job.

To schedule a Fetch Logs job, use the GET Agents operation with a query of Status -eq 2 and Capabilities -contains "LOGS" to retrieve a list of your approved orchestrators with the LOGS capability to determine the ID of the orchestrator for which you want to retrieve logs.

To schedule a job using your custom job type, use the GET Agents operation with a query of Status -eq 2 to retrieve a list of your approved orchestrators to determine the ID of the orchestrator for which you want to schedule a custom job with your custom job type.
JobFields Body

An object that set the values for any optional job fields configured for the custom job type. The key is the field name and the value is the value for the field.

For example:

Copy 
"JobFields": {
   "Favorite Type of Pet": "Rat",
   "Mother's Birthday": "1952-05-21"
}
Note:  If a job field has been configured with a default value and you wish to accept the default value, the field does not need to be submitted along with the POST /OrchestratorJobs/Custom request. The default value will be set automatically by Keyfactor Command. Submitting a value overrides the default value.

Use the GET Custom Job Types operation to retrieve a list of your defined custom job types to determine the job fields defined for the job type.

Tip:  The built-in Fetch Logs job does not have any optional job fields.
JobTypeName Body

Required. A string indicating the reference name for the custom job type for the job.

Use the GET Custom Job Types operation to retrieve a list of your defined custom job types to determine the job type name to use.
Schedule Body

An object containing the schedule for the custom job. ClosedShow schedule details.

The default is Immediate.

Table 624: POST Orchestrator Jobs Custom Response Data V1

Name Description
JobFields

An array of objects that set the values for any optional job fields configured for the custom job type.
JobId A string indicating the Keyfactor Command reference GUID for the job.
JobTypeName

A string indicating the reference name for the custom job type for the job.
OrchestratorId

A string indicating the Keyfactor Command reference GUID of the orchestrator that will execute this job.
OrchestratorPoolId

A string indicating the Keyfactor Command reference GUID of the orchestrator pool that will execute this job.
RequestTimestmap A string containing the date, in UTC, when the custom job was submitted.
Schedule

An object containing the schedule for the custom job.
Tip:  See the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. Reference and Utility, which allows you to call API operations and view results. It is primarily intended for validation, testing, and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.