diff --git a/src/_data/toc/graphql.yml b/src/_data/toc/graphql.yml index 4bf3f8da9dc..2c02390c964 100644 --- a/src/_data/toc/graphql.yml +++ b/src/_data/toc/graphql.yml @@ -223,6 +223,11 @@ pages: edition: b2b-only exclude_versions: ["2.3"] + - label: createCompanyUser mutation + url: /graphql/mutations/create-company-user.html + edition: b2b-only + exclude_versions: ["2.3"] + - label: createCustomer mutation url: /graphql/mutations/create-customer.html @@ -265,6 +270,11 @@ pages: edition: b2b-only exclude_versions: ["2.3"] + - label: deleteCompanyUser mutation + url: /graphql/mutations/delete-company-user.html + edition: b2b-only + exclude_versions: ["2.3"] + - label: deleteCustomerAddress mutation url: /graphql/mutations/delete-customer-address.html @@ -392,6 +402,11 @@ pages: edition: b2b-only exclude_versions: ["2.3"] + - label: updateCompanyUser mutation + url: /graphql/mutations/update-company-user.html + edition: b2b-only + exclude_versions: ["2.3"] + - label: updateCustomer mutation url: /graphql/mutations/update-customer.html diff --git a/src/guides/v2.4/graphql/mutations/create-company-user.md b/src/guides/v2.4/graphql/mutations/create-company-user.md new file mode 100644 index 00000000000..2170e046c33 --- /dev/null +++ b/src/guides/v2.4/graphql/mutations/create-company-user.md @@ -0,0 +1,189 @@ +--- +group: graphql +title: createCompanyUser mutation +contributor_name: Atwix +contributor_link: https://www.atwix.com/ +b2b_only: true +--- + +The `createCompanyUser` mutation allows an existing company user who is assigned a role that contains the `Magento_Company::users_edit` permission to create a new company user. The specified email address determines how Magento processes the request. + +- If the email address is unique for the website, Magento immediately creates the company user. + +- If the email address belongs to a customer who is not a company user, Magento sends an invitation to join the company organization to the customer. When the customer accepts the invitation, Magento adds the customer to the company organization. + +- If the email address belongs to a customer who is part of any company organization, Magento returns the error "A customer with the same email already assigned to company". + +The `target_id` input attribute allows you to specify which node in the company structure will be the parent node of the company user. If you do not specify a value, the user will be assigned to the top-level (root) node of the company structure. + +You can get the `target_id` and the `role_id` with the [`company`]({{page.baseurl}}/graphql/queries/company.html) query. + +## Syntax + +```graphql +mutation { + createCompanyUser( + input: CompanyUserCreateInput! + ) { + CreateCompanyUserOutput + } +} +``` + +## Example usage + +### Create a company user (minimal payload) + +The following example shows the minimal payload to add a company user. Because a `target_id` is not specified, Magento places the new company user at the top node of the company structure. + +**Request:** + +```graphql +mutation { + createCompanyUser( + input: { + email: "john.doe@example.com" + firstname: "John" + lastname: "Doe" + job_title: "User" + role_id: "MQ==" + status: ACTIVE + telephone: "1234567890" + } + ) { + user { + created_at + email + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "createCompanyUser": { + "user": { + "created_at": "2020-10-15 23:33:49", + "email": "john.doe@example.com" + } + } + } +} +``` + +### Create a company user in a specific location in the company structure + +This example creates a new company user of the parent company team specified in the `target_id` field. + +**Request:** + +```graphql +mutation { + createCompanyUser( + input: { + email: "jane.doe3@example.com" + firstname: "Jane" + lastname: "Doe3" + job_title: "User" + role_id: "NTc=" + status: ACTIVE + telephone: "1234567890" + target_id: "OA==" + } + ) { + user { + created_at + email + firstname + lastname + job_title + role { + id + name + } + team { + id + name + structure_id + } + status + telephone + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "createCompanyUser": { + "user": { + "created_at": "2020-10-15 23:39:11", + "email": "jane.doe@example.com", + "firstname": "Jane", + "lastname": "Doe", + "job_title": "User", + "role": { + "id": "NTc=", + "name": "Default User" + }, + "team": { + "id": "MQ==", + "name": "Test Team", + "structure_id": "Mg==" + }, + "status": "ACTIVE", + "telephone": "1234567890" + } + } + } +} +``` + +## Input attributes + +The `CompanyUserCreateInput` input object defines the company user data. + +### CompanyUserCreateInput attributes {#CompanyUserCreateInput} + +The `CompanyUserCreateInput` object contains the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`email` | String! | The company user's email address +`firstname` | String! | The company user's first name +`job_title` | String! | The company user's job title or function +`lastname` | String! | The company user's last name +`role_id` | ID! | The role ID to assign to the company user +`status` | CompanyUserStatusEnum! | Indicates whether the company user is ACTIVE or INACTIVE +`target_id` | ID | The ID of a node within a company's structure. This ID will be the parent of the created company user +`telephone` | String! | The company user's phone number + +## Output attributes + +The `CreateCompanyUserOutput` output object contains the following attribute: + +Attribute | Data Type | Description +--- | --- | --- +`user` | Customer! | Contains company user data + +### Customer attributes {#Customer} + +{% include graphql/customer-output-24.md %} + +## Errors + +Error | Description +--- | --- +`Invitation was sent to an existing customer, they will be added to your organization once they accept the invitation.` | The email provided in the `input`.`email` argument belongs to an existing customer. Magento will send an invitation to this customer. When the customer accepts the invitation, the customer will be assigned to the company. +`A customer with the same email already assigned to company.` | The email provided in the `input`.`email` argument belongs to an existing customer, and the customer has already been assigned to the company. +`"Email" is not a valid email address.` | The value provided in the `input`.`email` argument has an invalid format. +`Field "createCompanyUser" argument "input" requires type String!, found xxx.` | The value specified in the one of the `input` arguments has an invalid type. +`Field "xxx" is not defined by type CompanyUserCreateInput.` | The `input`.`xxx` argument is undefined. +`Required parameters are missing: xxx` | The `input`.`xxx` argument was omitted or contains an empty value. +`No such entity with roleId = xxx` | The company role with ID `xxx` doesn't exist. diff --git a/src/guides/v2.4/graphql/mutations/delete-company-user.md b/src/guides/v2.4/graphql/mutations/delete-company-user.md new file mode 100644 index 00000000000..6e0d65a3a75 --- /dev/null +++ b/src/guides/v2.4/graphql/mutations/delete-company-user.md @@ -0,0 +1,76 @@ +--- +group: graphql +title: deleteCompanyUser mutation +contributor_name: Atwix +contributor_link: https://www.atwix.com/ +b2b_only: true +--- + +Use the `deleteCompanyUser` mutation to deactivate the specified company user. + +You can get the user ID with the [`company`]({{page.baseurl}}/graphql/queries/company.html) query. + +## Syntax + +```graphql +mutation { + deleteCompanyUser( + id: ID! + ) { + DeleteCompanyUserOutput + } +} +``` + +## Example usage + +The following example deactivates the user specified in the `id` attribute. + +**Request:** + +```graphql +mutation { + deleteCompanyUser( + id: "Mg==" + ) { + success + } +} +``` + +**Response:** + +```json +{ + "data": { + "deleteCompanyUser": { + "success": true + } + } +} +``` + +## Input attributes + +The `deleteCompanyUser` mutation requires the following input: + +Attribute | Data Type | Description +--- | --- | --- +`id` | ID! | The encoded user ID to deactivate + +## Output attributes + +The `deleteCompanyUser` mutation returns a Boolean value that indicates whether the operation was successful. + +Attribute | Data Type | Description +--- | --- | --- +`success` | Boolean! | A value of `true` indicates the company user has been deactivated successfully, otherwise a value returns `false` + +## Errors + +Error | Description +--- | --- +`You do not have authorization to perform this action.` | The user with the ID provided in the `input`.`id` argument is not available to your company, or you do not have the necessary permissions to perform this operation. +`You cannot delete yourself.` | You must specify a company user other than yourself. +`A customer with the same email address already exists in an associated website` | The email provided in the `input`.`email` argument belongs to another user. +`The user XXX is the company admin and cannot be set to inactive. You must set another user as the company admin first.` | The company owner cannot be deactivated. You must set another user as the company admin first. diff --git a/src/guides/v2.4/graphql/mutations/update-company-user.md b/src/guides/v2.4/graphql/mutations/update-company-user.md new file mode 100644 index 00000000000..6b13ee43053 --- /dev/null +++ b/src/guides/v2.4/graphql/mutations/update-company-user.md @@ -0,0 +1,171 @@ +--- +group: graphql +title: updateCompanyUser mutation +contributor_name: Atwix +contributor_link: https://www.atwix.com/ +b2b_only: true +--- + +Use the `updateCompanyUser` mutation to update an existing company user. + +You can get the user ID and role ID with the [`company`]({{page.baseurl}}/graphql/queries/company.html) query. + +## Syntax + +```graphql +mutation { + updateCompanyUser( + input: CompanyUserUpdateInput! + ) { + UpdateCompanyUserOutput + } +} +``` + +## Example usage + +The following example changes the job title of the specified company user. + +**Request:** + +```graphql +mutation { + updateCompanyUser( + input: { + id: "Mg==" + job_title: "Company User" + } + ) { + user { + email + firstname + lastname + job_title + telephone + status + role { + id + name + users_count + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "updateCompanyUser": { + "user": { + "email": "jane.doe@example.com", + "firstname": "Jane", + "lastname": "Doe", + "job_title": "Company User", + "telephone": "1234567890", + "status": "ACTIVE", + "role": { + "id": "MQ==", + "name": "Default User", + "users_count": 1 + } + } + } + } +} +``` + +This example deactivates the company user and assigns a different role. + +**Request:** + +```graphql +mutation { + updateCompanyUser( + input: { + id: "Mg==" + role_id: "MQ==" + status: INACTIVE + } + ) { + user { + email + firstname + lastname + job_title + telephone + status + role { + id + name + users_count + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "updateCompanyUser": { + "user": { + "email": "jane.doe@example.com", + "firstname": "Jane", + "lastname": "Doe", + "job_title": "Company User", + "telephone": "1234567890", + "status": "INACTIVE", + "role": { + "id": "MQ==", + "name": "Default User", + "users_count": 1 + } + } + } + } +} +``` + +## Input attributes + +The `CompanyUserUpdateInput` input object defines the company user data. + +### CompanyUserUpdateInput attributes {#CompanyUserUpdateInput} + +The `CompanyUserUpdateInput` object contains the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`email` | String | The company user's email address +`firstname` | String | The company user's first name +`id` | ID! | The encoded user ID of the company user to be updated +`job_title` | String | The company user's job title or function +`lastname` | String | The company user's last name +`role_id` | ID | The ID of the role assigned to the company user +`status` | CompanyUserStatusEnum | Indicates whether the company user is ACTIVE or INACTIVE +`telephone` | String | The company user's phone number + +## Output attributes + +The `UpdateCompanyUserOutput` output object contains the following attribute: + +Attribute | Data Type | Description +--- | --- | --- +`user` | Customer! | Contains company user data + +### Customer attributes {#Customer} + +{% include graphql/customer-output-24.md %} + +## Errors + +Error | Description +--- | --- +`You do not have authorization to perform this action.` | The user with the ID provided in the `input`.`id` argument is not assigned to your company. +`No such entity with roleId = xxx` | The company role with ID `xxx` doesn't exist. +`A customer with the same email address already exists in an associated website` | The email provided in the `input`.`email` argument belongs to another user.