GraphQL: Replace list of company role permissions with a structural view (#8298)

* GraphQL: Replace list of company role permissions with a structural view

* move paragraph

* add whitespace

* Apply suggestions from code review

Co-authored-by: Erik Marr <[email protected]>

Co-authored-by: Erik Marr <[email protected]>

Author: keharper

src/_includes/b2b/company/company-acl.md

@@ -6,7 +6,11 @@ contributor_link: https://www.atwix.com/
 b2b_only: true
 ---
 
-Use the `createCompanyRole` mutation to create a new company role and permissions.
+The `createCompanyRole` mutation defines a new company role. To create a role, you must provide an array of permissions that determine which resources the user can access.
+
+{% include webapi/b2b_roles.md %}
+
+Also, you can get the list of all resources defined within the company using the [`company`]({{page.baseurl}}/graphql/queries/company.html) query.
 
 ## Syntax
 
@@ -121,12 +125,6 @@ Attribute |  Data Type | Description
 `name` | String! | Role name.
 `permissions` | [String!]! | A list of Role permission resources. Required array value for a field with strings as values of array.
 
-### Available permissions
-
-{% include b2b/company/company-acl.md %}
-
-Also, you can get the list of all resources defined within the company using [`company`]({{page.baseurl}}/graphql/queries/company.html) query.
-
 ## Output attributes
 
 The `CreateCompanyRoleOutput` output object contains the following attribute:

src/guides/v2.4/graphql/mutations/create-company-role.md

@@ -8,7 +8,9 @@ b2b_only: true
 
 Use the `updateCompanyRole` mutation to update the company role and permissions.
 
-You can get the role ID with the [`company`]({{page.baseurl}}/graphql/queries/company.html) query.
+You can get the role ID and the list of all resources defined within the company using the [`company`]({{page.baseurl}}/graphql/queries/company.html) query.
+
+{% include webapi/b2b_roles.md %}
 
 ## Syntax
 
@@ -163,12 +165,6 @@ Attribute |  Data Type | Description
 `name` | String | Role name.
 `permissions` | [String!] | A list of role permission resources.
 
-### Available permissions
-
-{% include b2b/company/company-acl.md %}
-
-Also, you can get the list of all resources defined within the company using [`company`]({{page.baseurl}}/graphql/queries/company.html) query.
-
 ## Output attributes
 
 The `UpdateCompanyRoleOutput` output object contains the following attribute: