Merge pull request #1757 from rwellon/RW-IAE-API

Create configuration_script_payloads API doc
ManageIQ · Dec 6, 2023 · 87501e1 · 87501e1
2 parents ba83c60 + f6617bb
commit 87501e1
Showing 1 changed file with 394 additions and 0 deletions.
diff --git a/api/reference/configuration_script_payloads.md b/api/reference/configuration_script_payloads.md
@@ -0,0 +1,394 @@
+---
+---
+
+## Configuration Script Payloads
+
+Management of configuration script payloads is provided through the following
+collection:
+
+``` data
+/api/configuration_script_payloads
+```
+
+The following actions on configuration script payloads are available:
+
+- [Querying Configuration Script Payloads](#querying-configuration-script-payloads)
+
+- [Editing Configuration Script Payloads](#editing-configuration-script-payloads)
+
+- [Updating Configuration Script Payloads](#updating-configuration-script-payloads)
+
+- [Querying Configuration Script Payload Authentication](#querying-configuration-script-payload-authentication)
+
+- [Creating Configuration Script Payload Authentication](#creating-configuration-script-payload-authentication)
+
+### Querying Configuration Script Payloads
+
+Query all configuration script payloads in the system:
+
+    GET /api/configuration_script_payloads
+
+Example response:
+
+``` json
+{
+  "name": "configuration_script_payloads",
+  "count": 2,
+  "subcount": 2,
+  "pages": 1,
+  "resources": [
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/1"
+    },
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/1"
+    }
+  ],
+  "actions": [
+    {
+      "name": "edit",
+      "method": "post",
+      "href": "http://localhost:3000/api/configuration_script_payloads"
+    }
+  ],
+  "links": {
+    "self": "http://localhost:3000/api/configuration_script_payloads?offset=0",
+    "first": "http://localhost:3000/api/configuration_script_payloads?offset=0",
+    "last": "http://localhost:3000/api/configuration_script_payloads?offset=0"
+  }
+}
+```
+
+Query the details on a specific configuration script payload:
+
+    GET /api/configuration_script_payloads/:id
+
+Example response:
+
+``` json
+{
+  "href": "http://localhost:3000/api/configuration_script_payloads/1",
+  "id": "1",
+  "manager_id": "2",
+  "manager_ref": null,
+  "name": "provision-vm-service/list-providers.asl",
+  "description": null,
+  "variables": null,
+  "created_at": "2023-11-08T17:43:30Z",
+  "updated_at": "2023-11-08T17:46:03Z",
+  "survey_spec": null,
+  "inventory_root_group_id": null,
+  "type": "ManageIQ::Providers::Workflows::AutomationManager::Workflow",
+  "parent_id": null,
+  "configuration_script_source_id": "11",
+  "run_by_userid": null,
+  "payload": "{\n  \"Comment\": \"List Providers.\",\n  \"StartAt\": \"ListProviders\",\n  \"States\": {\n    \"ListProviders\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"docker://docker.io/agrare/list-providers:latest\",\n      \"End\": true,\n      \"Credentials\": {\n        \"api_user.$\": \"$.api_user\",\n        \"api_password.$\": \"$.api_password\",\n        \"api_token.$\": \"$.api_token\",\n        \"api_bearer_token.$\": \"$.api_bearer_token\"\n      },\n      \"Parameters\": {\n        \"API_URL.$\": \"$$.Execution._manageiq_api_url\",\n        \"VERIFY_SSL.$\": \"$.dialog.dialog_verify_ssl\",\n\n        \"PROVIDER_TYPE\": \"ManageIQ::Providers::Vmware::InfraManager\"\n      }\n    }\n  }\n}\n",
+  "payload_type": "json",
+  "credentials": null,
+  "context": null,
+  "output": null,
+  "status": null,
+  "miq_task_id": null,
+  "payload_valid": true,
+  "payload_error": null,
+  "actions": [
+    {
+      "name": "edit",
+      "method": "post",
+      "href": "http://localhost:3000/api/configuration_script_payloads/1"
+    },
+    {
+      "name": "edit",
+      "method": "patch",
+      "href": "http://localhost:3000/api/configuration_script_payloads/1"
+    },
+    {
+      "name": "edit",
+      "method": "put",
+      "href": "http://localhost:3000/api/configuration_script_payloads/1"
+    }
+  ]
+}
+```
+
+### Editing configuration script payloads
+
+Configuration script payloads can be edited by using a POST to the configuration script payloads collection:
+
+    POST /api/configuration_script_payloads
+
+
+POST /api/configuration_script_payloads
+
+``` json
+{
+  "action": "edit",
+  "resources": [
+    {"id": 1, "description": "A Helpful Description"}
+  ]
+}
+```
+
+Example response:
+
+``` json
+{
+  "results": [
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/1",
+      "description": "A Helpful Description",
+      "credentials": {
+        "api_user.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "userid"
+        },
+        "api_password.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "password"
+        }
+      },
+      "id": "1",
+      "manager_id": "2",
+      "manager_ref": null,
+      "name": "provision-vm-service/list-providers.asl",
+      "variables": null,
+      "created_at": "2023-11-08T17:43:30Z",
+      "updated_at": "2023-11-15T20:14:28Z",
+      "survey_spec": null,
+      "inventory_root_group_id": null,
+      "type": "ManageIQ::Providers::Workflows::AutomationManager::Workflow",
+      "parent_id": null,
+      "configuration_script_source_id": "2",
+      "run_by_userid": null,
+      "payload": "{\n  \"Comment\": \"List Providers.\",\n  \"StartAt\": \"ListProviders\",\n  \"States\": {\n    \"ListProviders\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"docker://docker.io/agrare/list-providers:latest\",\n      \"End\": true,\n      \"Credentials\": {\n        \"api_user.$\": \"$.api_user\",\n        \"api_password.$\": \"$.api_password\",\n        \"api_token.$\": \"$.api_token\",\n        \"api_bearer_token.$\": \"$.api_bearer_token\"\n      },\n      \"Parameters\": {\n        \"API_URL.$\": \"$$.Execution._manageiq_api_url\",\n        \"VERIFY_SSL.$\": \"$.dialog.dialog_verify_ssl\",\n\n        \"PROVIDER_TYPE\": \"ManageIQ::Providers::Vmware::InfraManager\"\n      }\n    }\n  }\n}\n",
+      "payload_type": "json",
+      "context": null,
+      "output": null,
+      "status": null,
+      "miq_task_id": null,
+      "payload_valid": true,
+      "payload_error": null
+    }
+  ]
+}
+```
+
+
+For instance, configuration script payloads can be edited to map credentials:
+
+    POST /api/configuration_script_payloads
+
+``` json
+{
+  "action": "edit",
+  "resources": [
+    {
+      "id": 1,
+      "credentials": [
+        {"my-cred-user": {"credential_ref": "my-credential", "credential_field": "userid"}},
+        {"my-cred-password": {"credential_ref": "my-credential", "credential_field": "password"}}
+      ]
+    }
+  ]
+}
+```
+
+### Updating configuration script payloads
+
+Configuration script payloads can be updated by using a PUT method or PATCH method.
+
+PUT method:
+
+    PUT /api/configuration_script_payloads/:id
+
+Example request:
+
+    PUT /api/configuration_script_payloads/1 {"description": "A Helpful Description"}
+
+Response:
+
+``` json
+{
+  "results": [
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/1",
+      "description": "A Helpful Description",
+      "credentials": {
+        "api_user.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "userid"
+        },
+        "api_password.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "password"
+        }
+      },
+      "id": "1",
+      "manager_id": "2",
+      "manager_ref": null,
+      "name": "provision-vm-service/list-providers.asl",
+      "variables": null,
+      "created_at": "2023-11-08T17:43:30Z",
+      "updated_at": "2023-11-15T20:14:28Z",
+      "survey_spec": null,
+      "inventory_root_group_id": null,
+      "type": "ManageIQ::Providers::Workflows::AutomationManager::Workflow",
+      "parent_id": null,
+      "configuration_script_source_id": "2",
+      "run_by_userid": null,
+      "payload": "{\n  \"Comment\": \"List Providers.\",\n  \"StartAt\": \"ListProviders\",\n  \"States\": {\n    \"ListProviders\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"docker://docker.io/agrare/list-providers:latest\",\n      \"End\": true,\n      \"Credentials\": {\n        \"api_user.$\": \"$.api_user\",\n        \"api_password.$\": \"$.api_password\",\n        \"api_token.$\": \"$.api_token\",\n        \"api_bearer_token.$\": \"$.api_bearer_token\"\n      },\n      \"Parameters\": {\n        \"API_URL.$\": \"$$.Execution._manageiq_api_url\",\n        \"VERIFY_SSL.$\": \"$.dialog.dialog_verify_ssl\",\n\n        \"PROVIDER_TYPE\": \"ManageIQ::Providers::Vmware::InfraManager\"\n      }\n    }\n  }\n}\n",
+      "payload_type": "json",
+      "context": null,
+      "output": null,
+      "status": null,
+      "miq_task_id": null,
+      "payload_valid": true,
+      "payload_error": null
+    }
+  ]
+}
+```
+
+### Patch method:
+
+    PATCH /api/configuration_script_payloads/:id
+
+Example request:
+
+    PATCH /api/configuration_script_payloads/1 {"description": "A Helpful Description"}
+
+Response:
+
+``` json
+{
+  "results": [
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/1",
+      "description": "A Helpful Description",
+      "credentials": {
+        "api_user.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "userid"
+        },
+        "api_password.$": {
+          "credential_ref": "manageiq_api",
+          "credential_field": "password"
+        }
+      },
+      "id": "1",
+      "manager_id": "2",
+      "manager_ref": null,
+      "name": "provision-vm-service/list-providers.asl",
+      "variables": null,
+      "created_at": "2023-11-08T17:43:30Z",
+      "updated_at": "2023-11-15T20:14:28Z",
+      "survey_spec": null,
+      "inventory_root_group_id": null,
+      "type": "ManageIQ::Providers::Workflows::AutomationManager::Workflow",
+      "parent_id": null,
+      "configuration_script_source_id": "2",
+      "run_by_userid": null,
+      "payload": "{\n  \"Comment\": \"List Providers.\",\n  \"StartAt\": \"ListProviders\",\n  \"States\": {\n    \"ListProviders\": {\n      \"Type\": \"Task\",\n      \"Resource\": \"docker://docker.io/agrare/list-providers:latest\",\n      \"End\": true,\n      \"Credentials\": {\n        \"api_user.$\": \"$.api_user\",\n        \"api_password.$\": \"$.api_password\",\n        \"api_token.$\": \"$.api_token\",\n        \"api_bearer_token.$\": \"$.api_bearer_token\"\n      },\n      \"Parameters\": {\n        \"API_URL.$\": \"$$.Execution._manageiq_api_url\",\n        \"VERIFY_SSL.$\": \"$.dialog.dialog_verify_ssl\",\n\n        \"PROVIDER_TYPE\": \"ManageIQ::Providers::Vmware::InfraManager\"\n      }\n    }\n  }\n}\n",
+      "payload_type": "json",
+      "context": null,
+      "output": null,
+      "status": null,
+      "miq_task_id": null,
+      "payload_valid": true,
+      "payload_error": null
+    }
+  ]
+}
+```
+
+
+### Querying Configuration Script Payload Authentication
+
+Query the authentication credentials for a specific configuration script payload:
+
+    GET /api/configuration_script_payloads/:id/authentications
+
+Example response:
+
+``` json
+{
+  "name": "authentications",
+  "count": 7,
+  "subcount": 1,
+  "pages": 1,
+  "resources": [
+    {
+      "href": "http://localhost:3000/api/configuration_script_payloads/2/authentications/3"
+    }
+  ],
+  "actions": [
+    {
+      "name": "create",
+      "method": "post",
+      "href": "http://localhost:3000/api/configuration_script_payloads/2/authentications"
+    }
+  ],
+  "links": {
+    "self": "http://localhost:3000/api/configuration_script_payloads/2/authentications?offset=0",
+    "first": "http://localhost:3000/api/configuration_script_payloads/2/authentications?offset=0",
+    "last": "http://localhost:3000/api/configuration_script_payloads/2/authentications?offset=0"
+  }
+}
+```
+
+Get the details on a specific authentication credential for a configuration script payload:
+
+    GET /api/configuration_script_payloads/:id/authentications/:id
+
+Example response:
+
+``` json
+{
+  "href": "http://localhost:3000/api/configuration_script_payloads/2/authentications/3",
+  "id": "3",
+  "name": "manageiq_api",
+  "authtype": null,
+  "userid": "admin",
+  "password": null,
+  "resource_id": "25",
+  "resource_type": "ExtManagementSystem",
+  "created_on": "2023-11-15T19:59:23Z",
+  "updated_on": "2023-11-15T19:59:23Z",
+  "last_valid_on": null,
+  "last_invalid_on": null,
+  "credentials_changed_on": null,
+  "status": null,
+  "status_details": null,
+  "type": "ManageIQ::Providers::Workflows::AutomationManager::WorkflowCredential",
+  "auth_key": null,
+  "fingerprint": null,
+  "service_account": null,
+  "public_key": null,
+  "manager_ref": "3",
+  "options": null,
+  "evm_owner_id": null,
+  "miq_group_id": "1",
+  "tenant_id": "1",
+  "become_username": null,
+  "become_password": null,
+  "auth_key_password": null,
+  "ems_ref": "manageiq_api",
+  "become_method": null
+}
+```
+
+
+### Creating Configuration Script Payload Authentication
+
+Authentication credentials for a configuration script payload can be created by using a POST to the configuration script payload collection:
+
+    POST /api/configuration_script_payloads/:id/authentications
+
+``` json
+{
+  "action": "create",
+  "description": "Description",
+  "name": "my credential",
+  "type": "ManageIQ::Providers::AnsibleTower::AutomationManager::Credential"
+}
+```