People Provisioning

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

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.


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:


where: { EmailAddress: { _eq: "email@domain.com" } }

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:


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 Titlesand/or People Types to get our system Ids if those are being updated:

To get Job Titles use the below query:


query getJobTitles {
  getJobTitles {
    JobTitleId
    JobTitle
  }
}

To get all of the People Types in your company use the below query


query getPeopleTypes {
  getPeopleTypes {
    PeopleTypeId
    PeopleTypeName
    CompanyID
  }
}

Finally update person using the below mutation:


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:


query GetCompanyOrgSchema {
    getCompanyOrgSchema {
        BusinessRegions {
            BusinessRegionId
            BusinessRegion
        }
        CompanyCountries {
            Id
            Name
        }
        Departments {
            DepartmentId
            DepartmentName
        }
    }
}

Assign/attach org schemas to person:


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:


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 .