From b1af27c4f61acf22a1f088616d2128c09beb0844 Mon Sep 17 00:00:00 2001
From: Nikhil <jainnikhil30@gmail.com>
Date: Thu, 23 Feb 2023 10:47:22 +0530
Subject: [PATCH] add more docs on the bulk job launch feature

better error message
---
 awx/api/serializers.py |  2 +-
 docs/bulk_api.md       | 57 ++++++++++++++++++++++++++++++------------
 2 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/awx/api/serializers.py b/awx/api/serializers.py
index 13b2895815..3c93f7e5d2 100644
--- a/awx/api/serializers.py
+++ b/awx/api/serializers.py
@@ -2052,7 +2052,7 @@ class BulkHostCreateSerializer(serializers.Serializer):
         try:
             Host.objects.bulk_create(result)
         except Exception as e:
-            raise serializers.ValidationError({"detail": _(f"{e}")})
+            raise serializers.ValidationError({"detail": _(f"cannot create host, host creation error {e}")})
         new_total_hosts = old_total_hosts + len(result)
         request = self.context.get('request', None)
         changes = {'total_hosts': [old_total_hosts, new_total_hosts]}
diff --git a/docs/bulk_api.md b/docs/bulk_api.md
index 40f51d8776..c35adbc6c2 100644
--- a/docs/bulk_api.md
+++ b/docs/bulk_api.md
@@ -10,30 +10,55 @@ Provides feature in the API that allows a single web request to achieve multiple
 
 Following is an example of a post request at the /api/v2/bulk/job_launch
 
-```commandline
-{
-"name": "Bulk Job Launch",
-"jobs": [
-   {"unified_job_template": 7, "identifier":"foo", "limit": "kansas", "credentials": [1]},
-   {"unified_job_template": 8, "identifier":"bar", "inventory": 1, "execution_environment": 3},
-   {"unified_job_template": 9}
-]
-}
-```
+    {
+        "name": "Bulk Job Launch",
+        "jobs": [
+            {"unified_job_template": 7},
+            {"unified_job_template": 8},
+            {"unified_job_template": 9}
+        ]
+    }
 
 The above will launch a workflow job with 3 nodes in it. 
 
+**Important Note: A bulk job launched by a normal user will not be visible in the jobs section of the UI, although the individual jobs within a bulk job can be seen there.** 
+
+If the job template has fields marked as prompt on launch, those can be provided for each job in the bulk job launch as well:
+
+    {
+        "name": "Bulk Job Launch",
+        "jobs": [
+            {"unified_job_template": 11, "limit": "kansas", "credentials": [1], "inventory": 1}
+        ]
+    }
+
+In the above example `job template 11` has limit, credentials and inventory marked as prompt on launch and those are provided as parameters to the job.
+
+Prompted field value can also be provided at the top level. For example:
+
+    {
+        "name": "Bulk Job Launch",
+        "jobs": [
+            {"unified_job_template": 11, "limit": "kansas", "credentials": [1]},
+            {"unified_job_template": 12},
+            {"unified_job_template": 13}
+        ],
+        "inventory": 2
+    }
+
+In the above example, `inventory: 2` will get used for the job templates (11, 12 and 13) in which inventory is marked as prompt of launch.
+
 ## Bulk Host Create
 
 Provides feature in the API that allows a single web request to create multiple hosts in an inventory.  
 
 Following is an example of a post request at the /api/v2/bulk/host_create:
 
-```commandline
-{
-    "inventory": 1,
-    "hosts": [{"name": "host1", "variables": "ansible_connection: local"}, {"name": "host2"}, {"name": "host3"}, {"name": "host4"}, {"name": "host5"}, {"name": "host6"}]
-}
-```
+
+    {
+        "inventory": 1,
+        "hosts": [{"name": "host1", "variables": "ansible_connection: local"}, {"name": "host2"}, {"name": "host3"}, {"name": "host4"}, {"name": "host5"}, {"name": "host6"}]
+    }
+
 
 The above will add 6 hosts in the inventory.
\ No newline at end of file