The Create or Update PowerShell task operation will create or update a PowerShell automation task.
Request
Request URI
| Method | Request URI |
|---|---|
| POST | https://{company-name}.helloid.com/api/v1/automationtasks/powershell |
Request parameters
| Parameter | Description |
|---|---|
| {company-name} | The company name of the target company |
Request headers
| Header | Description |
|---|---|
| Content-Type | Required. Must be set to application/json. |
Sample request body
{
"name": "New PowerShell Task",
"automationContainer": 1,
"objectGuid": "daca4ced-a07f-4e13-afe9-c972bad6cdea",
"agentPoolGuid": null,
"emailAddresses": "me@example.com",
"scriptTimeout": 0,
"uSN": 1,
"metaData": null,
"isEnabled": true,
"sendMail": true,
"isScriptTimeoutEnabled": false,
"sendMailWhenFailed": false,
"sendMailForCriticalEvent": false,
"useTemplate": false,
"powerShellScriptTemplateGuid": null,
"powerShellScript": "$test = 0",
"variables": [
{
"name": "variablename",
"value": "variablevalue",
"typeConstraint": "string",
"secret": false
}
]
}
Request body parameters
| Parameter | Description | Required/Optional | Default value |
|---|---|---|---|
| {name} | Name of the automation task | Required | - |
| {automationContainer} |
Automation container for the automation task. Determines the type of object that is linked through the {automationTaskGuid} parameter. If no object is supplied, then {automationContainer} should have the value "1" since it is just a Powershell task. PowerShell = 1, |
Required | - |
| {automationTaskGuid} | Guid of an existing task in order to update it. | Optional | - |
| {objectGuid} | Guid of an existing object to link this task to. i.e. a selfservice product or delegated form. | Optional | - |
| {agentPoolGuid} | Agentpool that will be used to execute the PowerShell task | Optional | - |
| {emailAddresses} | List of email addresses that are notified when a task finishes | Optional | - |
| {scriptTimeout} | Timeout after which the task will be killed when it's still running (when option is set to enabled) | Optional | - |
| {uSN} | Synchronization counter | Optional | 1 |
| {metaData} |
In the case of a selfservice product, on which state the task will be executed. {"executeOnState":1}
|
Optional | - |
| {isEnabled} | Is the task enabled | Optional | true |
| {sendMail} | Should e-mail be sent when task finishes | Optional | false |
| {isScriptTimeoutEnabled} | Should task be killed what it hasn't finished after the timeout. | Optional | false |
| {sendMailWhenFailed} | Should e-mail be sent when task failed | Optional | false |
| {sendMailForCriticalEvent} | Should e-mail be sent in case of a critical event | Optional | false |
| {useTemplate} | Flag indicating where the task will use a PowerShell template or an inline PowerShell script | Optional | false |
| {powerShellScriptTemplateGuid} | Identifier of a PowerShell template. Required when useTemplate is set to true | Required when useTemplate is true | - |
| {powerShellScript} | PowerShell script that will be executed | Required when useTemplate is false | - |
| {variables} | Variables that can be used by the PowerShell task | Optional | - |
Generated fields
The automationTaskGuid field will be auto-generated by HelloID.
Response
Response status
| Code | Description |
|---|---|
| 200(OK) | Indicates that the operation was successful and the resource is created. |
| 400(BAD REQUEST) | Indicates that the operation was not successful. There were validation errors or the request body was malformed.If there were validation errors, the response will include a error result. |
| 401(UNAUTHORIZED) | Indicates that no authentication header was given or the api key and secret were invalid. If the api key and secret were valid check the configuration in your portal, it is possibilty these were IP restricted or are disabled. |
Please also see error result.
Please also see common HTTP status codes.
Sample response body
{
"automationTaskGuid": "55b1135f-30c8-41de-92e6-482dee34ec2f",
"id": "4d20769f-80f1-48f6-acd1-33e642aa211d",
"name": "New PowerShell Task",
"type": "native",
"version": "1.0.*",
"isValid": true,
"executionType": "native",
"executionEntry": "powershell-script",
"executionEnvironment": "helloid-agent",
"executionMinimumVersion": "1.1.0",
"editor": "custom-powershell-script",
"objectGuid": "daca4ced-a07f-4e13-afe9-c972bad6cdea",
"agentPoolGUID": null,
"metaData": null,
"variables": [
{
"automationVariableGuid": "63361071-7778-4d1b-8351-cf00556ea226",
"name": "powerShellScript",
"value": "$test = 0",
"secret": false
},
{
"automationVariableGuid": "7723158b-b18b-4119-8297-43d35f8d9a2b",
"name": "powerShellScriptGuid",
"value": null,
"secret": false
},
{
"automationVariableGuid": "85675f64-c9d9-4e9a-a9ba-702c16bd4653",
"name": "useTemplate",
"value": "False",
"secret": false
},
{
"automationVariableGuid": "22e1cfc6-7668-4a6a-a020-cb3b04e02623",
"name": "variablename",
"value": "variablevalue",
"secret": false
}
],
"contexts": [
"automation"
],
"isNew": false,
"isEnabled": true,
"isTemporary": false,
"automationContainer": 1
}
Example request with cURL
Replace placeholder values surrounded by { } with the actual values.
curl -u {api-key}:{api-secret} -X POST https://{company-name}.helloid.com/api/v1/automation/variable/var1 -H "Content-Type:application/json" -d
"{
'name': 'New PowerShell Task',
'automationContainer': 1,
'objectGuid': 'daca4ced-a07f-4e13-afe9-c972bad6cdea',
'agentPoolGuid': null,
'emailAddresses': 'me@example.com',
'scriptTimeout': 0,
'uSN': 1,
'metaData': null,
'isEnabled': true,
'sendMail': true,
'isScriptTimeoutEnabled': false,
'sendMailWhenFailed': false,
'sendMailForCriticalEvent': false,
'useTemplate': false,
'powerShellScriptTemplateGuid': null,
'powerShellScript': '$test = 0',
'variables': [
{
'name': 'variablename',
'value': 'variablevalue',
'typeConstraint': 'string',
'secret': false
}
]
}"