> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# People Provisioning

> This guides you on which GraphQL operations to create, update and view people in your company on SkillsDB.

<Info>
  **Quick Summary:** This tutorial covers the GraphQL operations for creating, updating, and viewing people in your SkillsDB company, including migration paths from the legacy API.
</Info>

### Get List of People

* On the **legacy API** access the below API were used to retrieve list of employee/people details.
  * `GET - {{baseURI}}/Personnel/Get/{{companyID}}?part={{part}}`
* On the **new GraphQL API** the below query will be used to retrieve/list all people. Please refer to Filtering and Sorting documentations for more details about filtering and sorting.

```graphql theme={null}
query GetAllPeople {
    getAllPeople(
        limit: 10
        offset: 0
        orderBy: { FirstName: ASC, LastName: ASC, EmailAddress: DESC }
        where: { EmailAddress: { _like: "" } }
    ) {
        count
        data {
            PersonID
            LastName
            FirstName
            EmailAddress
            GroupId
            NextAvailDate
            Gender
            Company
            BusinessPhone
            HomePhone
            MobilePhone
            FaxNumber
            Address
            City
            StateProvince
            ZipPostalCode
            PeopleCountries {
                CompanyCountry {
                    Id
                    Name
                }
            }
            WebPage
            Notes
            PeopleBusinessRegions {
                CompanyBusinessRegion {
                    BusinessRegionId
                    BusinessRegion
                }
            }
            PeopleDepartments {
                Department {
                    DepartmentId
                    DepartmentName
                }
            }
            JobTitle {
                JobTitleId
                JobTitle
            }
            PeopleType {
                PeopleTypeId
                PeopleTypeName
            }
            Manager {
                PersonID
                FirstName
                LastName
                EmailAddress
            }
            Active
            PeopleJobRoles {
                JobRole {
                    JobRoleId
                    JobRole
                    JobRoleLevels {
                        JobRoleLevelId
                        Title
                        SortOrder
                    }
                }
            }
        }
    }
}
```

### Get Person/Employee by Email

* The **legacy API** uses the below API to retrive
  * `GET - {{baseURI}}/Personnel/Get/Email/{{companyID}}?email={{email}}&part={{part}}`
* On the **new GraphQL API** we'll use the above query: `getAllPeople` with the filter as follow:

```graphql theme={null}
where: { EmailAddress: { _eq: "email@domain.com" } }
```

### Filter People created by specific user

* On the **new GraphQL API** we'll use the above query: `getAllPeople` with the filter as following:
  ```graphql theme={null}
   where: { CreatedByPersonId: { _eq: 4 } }
  ```

#### To get the person Id of the current session user, use the below query with the JWT auth header:

```graphql theme={null}
query me {
    me {
        PersonID
        FirstName
        LastName
        EmailAddress
        Active
        GroupId
    }
}
```

### Add or Update People/Employees

* On the **legacy API** the below API have been used to add or update a person profile:
  * `POST - {{baseURI}}/Personnel/Insert/{{companyID}}`
* On the **new GraphQL API** we'll use the below Mutations to insert and update an employee/person.

**Insert a new person:**

```graphql theme={null}
mutation addPersonCompotsite {
    addPersonComposite(
        input: {
            FirstName: "First Name"
            LastName: "Last Name"
            EmailAddress: "email@domain.com" # unique email address that is not added to our system
            SecurityGroup: GLOBAL_ADMIN # GLOBAL_ADMIN / MANAGER / EMPLOYEE
            YourPersonId: "Way-1234" # your system user id for the person
            Active: true
            ThirdPartyCompany: "Third Party Foundation"
            BusinessPhone: "101 101 101"
            MobilePhone: "202 202 202"
            HomePhone: "303 303 303"
            Address: "1 Wayne Street"
            Gender: Male # Male/Female
            FaxNumber: "404 404 404"
            Notes: "Notes on"
            StateProvince: "Gotham Province"
            WebPage: "https://wayne.com"
            ZipPostalCode: "46000"
            JobTitleName: "CTO" # define person's job title name (will be created if not exists)
            PeopleTypeName: "Technical" # define the person type name (this will be created if not exists)
            ManagersEmail: "manager@domain.com" # manager email address (the manager should be already added to our system)
            JobRoleNames: ["Deployments", "Software Development"] # JobRole. Specify multiple Job Roles to be assigned to a person.
            OrgSchema: {
                Countries: ["USA", "UK", "Finland"] # country_name. Specify multiple Countries to be attached to this user
                BusinessRegions: ["Los Gatos"] # BusinessRegion - specify multiple business regions
                Departments: ["Engineering"] # DepartmentName. Specify Multiple Departments.
            }
        }
    ) {
        id
        success
        message
    }
}
```

**CAUTION: This mutation will send welcome emails to users on production.**

**Update Existing Person**

To update a person the below mutation can be used. Before that we need get `Job Titles`and/or `People Types` to get our system Ids if those are being updated:

* To get **Job Titles** use the below query:
  ```graphql theme={null}
  query getJobTitles {
    getJobTitles {
      JobTitleId
      JobTitle
    }
  }
  ```
* To get all of the **People Types** in your company use the below query
  ```graphql theme={null}
  query getPeopleTypes {
    getPeopleTypes {
      PeopleTypeId
      PeopleTypeName
      CompanyID
    }
  }
  ```
* Finally **update person** using the below mutation:
  ```graphql theme={null}
  mutation EditPerson {
      editPerson(
          input: {
              PersonId: 123 # get from getAllPeople query
              LastName: "Last Name"
              FirstName: "First Name"
              YourPersonId: "1123654"
              SecurityGroupId: 7 # 7 for GlobalAdmin, 4 for Manager, 1 for Employee
              Gender: Male # Male/Female
              Company: "SDB"
              BusinessPhone: "444 4444 44"
              HomePhone: "4444 444 4444"
              MobilePhone: "+44444444444"
              FaxNumber: "45454545"
              Address: "Sample Address"
              City: "Sample city"
              StateProvince: "State province test"
              ZipPostalCode: "45454545"
              WebPage: "www.user.com"
              Notes: "This is a note."
              JobTitleId: 13 # get from getJobTitles query
              PeopleTypeId: 24 # get from getPeopleTypes
              ManagerEmailAddress: "tadesse@skillsdb.com"
              Active: false # activate or inactivate person
              AvoidUnassignmentForEmptyValues: true, # This flag determine to not unassign title, people type, manager when they have empty value
          }
      ) {
          success
          message
          rowsAffected
      }
  }
  ```
  * Provide the `AvoidUnassignmentForEmptyValues = true` so that the Manager, Job Title and People Type attributes do not get assigned null. If this field is not provided or is false, then these 3 attributes will be assigned null.
    * Always provide this value as true in every `editPerson` request unless you want to unassign/set null.
      Notice on the `editPerson` payload there is no org schema definition (i.e. department, country, business regions. To assign and/or unassign org schemas please the below query and mutation to get org schemas and assign/unassign from person
  * **Get list of org schemas**:
    ```graphql theme={null}
    query GetCompanyOrgSchema {
        getCompanyOrgSchema {
            BusinessRegions {
                BusinessRegionId
                BusinessRegion
            }
            CompanyCountries {
                Id
                Name
            }
            Departments {
                DepartmentId
                DepartmentName
            }
        }
    }
    ```
  * Assign/attach org schemas to person:
    ```graphql theme={null}
    mutation AttachOrgSchemaToPeople {
        attachOrgSchemaToPeople(
            input: {
                PersonId: 123 # person id in which the org schemas are attached/assigned to
                BusinessRegionIds: [123] # list of business regions ids to be attached/assigned to the person
                CountryIds: [321] # list of country ids to be attached/assigned to the person
                DepartmentIds: [432] # list of department ids to be attached/assigned to the person
            }
        ) {
            success
            message
            rowsAffected
        }
    }
    ```
  * Unassign/detach org schema from person:
    ```graphql theme={null}
    mutation DetachOrgSchemaFromPeople {
        detachOrgSchemaFromPeople(
            input: {
                PersonId: 123 # person id in which the org schemas are detached/unassigned from
                BusinessRegionIds: [123] # list of business regions ids to be detached/unassigned from the person
                CountryIds: [321] # list of country ids to be detached/unassigned from the person
                DepartmentIds: [432] # list of department ids to be detached/unassigned from the person
            }
        ) {
            success
            message
            rowsAffected
        }
    }
    ```
    You can get org schemas attached to a person from `getAllPeople` . i.e. `PeopleCountries`, `PeopleDepartments` , `PeopleBusinessRegions` .

***

# Need Help?

<Info>
  If you run into any issues or have questions, reach out to your organization's SkillsDB administrator or contact [SkillsDB Support](https://www.skillsdb.com/support).
</Info>