From 4d4accf89e50fec76de66a3e8fb90485e3a990ea Mon Sep 17 00:00:00 2001
From: ubanerjeeNR <ubanerjee@newrelic.com>
Date: Thu, 13 Feb 2025 23:13:49 +0530
Subject: [PATCH] feat(graphQL-apis): Added mutations for creating, updating,
 and deleting a custom role

---
 .../examples/nerdgraph-manage-groups.mdx      | 123 ++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/src/content/docs/apis/nerdgraph/examples/nerdgraph-manage-groups.mdx b/src/content/docs/apis/nerdgraph/examples/nerdgraph-manage-groups.mdx
index 9f5f637f67f..a47716c1fe7 100644
--- a/src/content/docs/apis/nerdgraph/examples/nerdgraph-manage-groups.mdx
+++ b/src/content/docs/apis/nerdgraph/examples/nerdgraph-manage-groups.mdx
@@ -274,6 +274,129 @@ Here's an example response:
                     },
 ```
 
+## Create a role [#create-role]
+
+Here's an example of creating a [role](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles):
+
+```graphql
+mutation {
+  customRoleCreate(
+    container: {
+      id: "$YOUR_ORGANIZATION_ID"
+      type: "ORGANIZATION"
+    }
+    name: "MY CUSTOM ROLE"
+    permissionIds: [1,2,3] 
+    scope: "ACCOUNT" 
+  ) {
+    id
+  }
+}
+```
+### Parameters
+- `container`:
+  - `id`: (String) The unique identifier of your organization. Replace $YOUR_ORGANIZATION_ID with your actual organization ID.
+  - `type`: (String) The type of container. Currently, the only supported type is "ORGANIZATION".
+  - `name`: (String) The name assigned to the custom role. Example: "MY CUSTOM ROLE".
+- `permissionIds`: (Array) A list of permission IDs representing the capabilities assigned to the custom role. Ensure these IDs correspond to valid permissions in your system.
+- `scope`: (String) The level at which the role's permissions apply. In this instance, the scope is "ACCOUNT".
+
+### Response
+- `id`: Returns the unique ID of the newly created custom role.
+
+    <Callout variant="important">
+      - Replace `$YOUR_ORGANIZATION_ID` with your specific organization ID before executing the mutation.
+      - Ensure that the `permissionIds` provided are valid and align with the permissions you want to grant.
+    </Callout>
+
+Before you create a custom role, you have to identify the permissions you want to assign to it.
+
+Use the following query to retrieve the list of permissions:
+
+```graphql
+mutation {
+  customerAdministration {
+    permissions {
+      items {
+        category
+        feature
+        id
+        product
+        subsetIds
+      }
+      nextCursor
+    }
+  }
+}
+```
+This returns account-scoped permissions. For permissions scoped to an org, run the following query instead:
+
+```graphql
+{
+  customerAdministration {
+    permissions(filter: {scope: {eq: "organization"}}) {
+      items {
+        category
+        feature
+        id
+        product
+        subsetIds
+      }
+      nextCursor
+    }
+  }
+}
+```
+
+Note the following fields:
+- `items`: An array of permission objects, each containing the following attributes:
+  - `category`: (String) The category or grouping the permission belongs to.
+  - `feature`: (String) The specific feature the permission is associated with.
+  - `id`: (String) A unique identifier for each permission.
+  - `product`: (String) The product that the permission applies to.
+  - `subsetIds`: (Array) A list of IDs representing subsets or related permissions.
+
+After you have the unique identifier for each permission you want to assign to the new role, create that role.
+
+## Update role [#update-role]
+
+Here's an example of updating a [role](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles).
+
+```graphql
+mutation {
+  customRoleUpdate(
+    id: $ROLE_ID
+    name: "MY NEW CUSTOM ROLE NAME"
+    permissionIds: [4,5,6] 
+  ) {
+    id
+  }
+}
+```
+
+### Parameters
+- `id`: The unique identifier of the custom role you wish to modify. Replace `$ROLE_ID` with the actual ID of the role.
+- `name`: The new name you want to assign to the custom role. In this example, it's `MY NEW CUSTOM ROLE NAME`.
+- `permissionIds`: An array of permission IDs you want to assign to this role. Ensure these IDs are valid and correspond to the permissions you intend to implement.
+
+## Delete a role [#delete-role]
+Here's an example of deleting a [role](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles):
+
+```graphql
+mutation {
+  customRoleDelete(
+    id: $ROLE_ID 
+  ) {
+    id
+  }
+}
+```
+
+### Parameters
+- `id`: The unique identifier of the role you wish to delete. Replace `$ROLE_ID` with the actual ID of the role you want to remove.
+### Response
+- `id`: Returns the ID of the role that has been deleted, confirming the successful execution of the mutation.
+
 ## Create a group [#create-group]
 
 Here's an example of creating a [group](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#groups):