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.
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" } }
Filter People created by specific user
- On the new GraphQL API we’ll use the above query:
getAllPeople with the filter as following:
where: { CreatedByPersonId: { _eq: 4 } }
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:
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
}
}
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
}
}
getAllPeople . i.e. PeopleCountries, PeopleDepartments , PeopleBusinessRegions .
Need Help?
If you run into any issues or have questions, reach out to your organization’s SkillsDB administrator or contact SkillsDB Support.