Requirements:
- Node.js 18+
- or Node.js 10+ with fetch and crypto polyfills
- npm v9+
Review the Client documentation for details on what Clients and Commands are.
The Workday Client is an extension of the default client that is specifically designed for making Workday API calls.
You can download the entire workday client by running npm install @byu-oit-sdk/client-workday.
If you don't want to load every single command into memory, you can download only the commands specific to a workday service as defined in the package.json (i.e. npm install @byu-oit-sdk/client-workday/admissions).
Initializing the client is simple. The Workday Client can be configured with some options to override the default behavior if desired.
const client = new WorkdayClient()
// or
const client = new WorkdayClient({ /* options here */ })Here are a list of supported options:
| Option | Type | Default Value | Purpose |
|---|---|---|---|
| logger |
Logger, from pino |
Pino() |
(Optional) Logging information from client functionality |
| credentials | CredentialProvider |
ChainedCredentialProvider() |
(Optional) The credential provider used resolving access tokens |
The default credential provider is
the Workday Credentials provider. Any of the parameters that it
accepts may be supplied via environment variables with the prefix WORKDAY_. If a different credential provider is
needed it should be configured and passed into the Workday Client constructor.
Here are a list of environment variables to include in your project with the specified prefix:
| Name | Description |
|---|---|
| ISSUER | The url required to call the desired workday instance (Should end at .com) |
| TENANT | The specific name/id of the tenant you are calling |
| REFRESH_TOKEN | The refresh token that is used to get a bearer token |
| CLIENT_ID | The clientId used for refresh token Oauth |
| CLIENT_SECRET | The clientSecret used for refresh token Oauth |
| VERSION | The version of the workday instance |
There is currently no retry strategy implemented for Workday.
All commands are available as methods on the class for convenience. For example:
const data = await client.getApplication({ applicationId: 'some-application-id' })Currently only commands in the following services are supported:
It is worth noting that many values you will need to provide must be what Workday is expecting. Since many of these are configurable please communicate with someone who is in control of the Workday instance you are using. We have set some values as defaults but have done our best to make it configurable.
workday command: Get_Student_Applications
Use this command to get an application
There is only one parameter: an object that contains an applicationId.
const command = new GetApplicationCommand({
applicationId: 'TEST_123'
})
const data = await client.send(command)See GetApplicationOutputSchema for information about the data that is returned.
workday command: Put_Student_Application
This command has TWO usages.
- Create an application (POST) OR
- Update certain fields of an application (PUT)
See PutApplicationInputSchema for information about the parameters to include. Various optional fields have default values so be sure to note those when reviewing the input options in case you need it to be something different.
Creating an application:
const command = new PutApplicationCommand({
applicationId: 'TEST_123',
applicantType: 'STUDENT_APPLICANT_TYPE-First_Year',
submittedDate: '2023-05-23',
admitMajor: 'PS_CSBS',
minorList: ['PS_MIANTH', 'PS_MIAS'],
admitPeriod: '2233',
studentTagList: ['IWORK'],
previousCollegeFlag: false,
firstGenerationFlag: false,
firstName: 'Test',
lastName: 'Applicant',
countryReference: 'USA',
dateOfBirth: '2000-01-01',
gender: 'Male',
ethnicity: 'White_United_States_of_America',
citizenshipStatus: 'Citizen_United_States_of_America',
hispanicFlag: false,
religionCode: 'LDS',
...
})
const data = await client.send(command)Updating an application: (Student_Prospect_Data is not included when updating an application, even if you include it in the input. You must use other workday commands to update that data.)
const command = new PutApplicationCommand({
addOnly: false, // MUST SET THIS TO FALSE
applicationId: 'TEST_123',
applicantType: 'STUDENT_APPLICANT_TYPE-First_Year',
submittedDate: '2023-05-23',
admitMajor: 'PS_CSBS',
minorList: ['PS_MIANTH', 'PS_MIAS'],
admitPeriod: '2233',
studentTagList: ['Hukilau', 'DPS'],
countryReference: 'USA',
firstName: 'Test',
lastName: 'Applicant',
...
})
const data = await client.send(command)See PutApplicationOutputSchema for information about the data that is returned.
workday command: Import_Student_Application_GPA_Assignment_Values
Use this command to add high school or college GPA to an application See PutGpaInputSchema for information about the parameters to include.
const command = new PutGpaCommand({
applicationId: 'TEST_123',
selfReportedHighSchoolGPA: 3.92
})
const data = await client.send(command)See PutGpaOutputSchema for information about the data that is returned.
workday command: Import_Student_Application_Admission_Decision
Use this command to add a decision to an application. See ImportDecisionInputSchema for information about the parameters to include.
const command = new ImportDecisionCommand({
applicationId: 'TEST_123',
decisionDate: '2024-05-29',
admissionDecisionId: 'Admit',
admissionDecisionReasonId: 'Ugrd_Admit',
/* following fields only included for admit decisions */
programOfStudyId: 'PS_CSBS',
admitPeriod: '2233',
campusReference: 'BYUH'
})
const data = await client.send(command)See ImportDecisionOutputSchema for information about the data that is returned.
workday command: Put_Student_Application_Admission_Response
Use this command to add intent to enroll to an application. Note that the application must be published by an admissions officer in Workday. See PutAdmissionResponseInputSchema for information about the parameters to include.
const command = new PutAdmissionResponseCommand({
applicationId: 'TEST8',
intentToEnroll: {
response: 'ACCEPTED_OFFER_OF_ADMISSION',
reason: 'Accept_Accept'
},
admitPeriod: '2233'
})
const data = await client.send(command)See PutAdmissionResponseOutputSchema for information about the data that is returned.
workday command: Submit_Student_Application_Withdrawal
Use this command to withdraw an application. See WithdrawApplicationInputSchema for information about the parameters to include.
const command = new WithdrawApplicationCommand({
applicationId: 'TEST_123',
decisionDate: '2024-05-29'
})
const data = await client.send(command)See WithdrawApplicationOutputSchema for information about the data that is returned.
workday command: Import_Student_Application_Change_Published_Admissions_Decision_Details
Use this command to change a decision on an application. See ChangePublishedDecisionDetailsInputSchema for information about the parameters to include.
const command = new ChangePublishedDecisionDetailsCommand({
applicationId: 'TEST_123',
programOfStudyId: 'PS_CSBS',
admitPeriod: '2233'
})
const data = await client.send(command)See ChangePublishedDecisionDetails for information about the data that is returned.
workday command: Submit_Change_Application_Anticipated_Start
Use this command to change the admit period on an application. See ChangeApplicationStartInputSchema for information about the parameters to include.
const command = new ChangeAnticipatedStartCommand({
applicationId: 'TEST_123',
dateOfChange: '2023-05-23',
academicPeriod: '2235'
})
const data = await client.send(command)See ChangeApplicationStartOutputSchema for information about the data that is returned.
workday command: Submit_Change_Application_Program_of_Study
Use this command to change the program of study on an application. See ChangeProgramOfStudyInputSchema for information about the parameters to include.
const command = new ChangeProgramOfStudyCommand({
applicationId: 'TEST_123',
programId: 'PS_CSBS',
order: '0'
})
const data = await client.send(command)See ChangeProgramOfStudyOutputSchema for information about the data that is returned.
workday command: Put_Education_Test_Result
Use this command to add, update, or delete test scores (ACT, SAT, etc.) for a student. See GetEducationTestResultInputSchema for information about the parameters to include. Various optional fields have default values so be sure to note those when reviewing the input options in case you need it to be something different.
The default studentReferenceId type is Academic_Person_ID
Add a Test Result:
const command = new PutGpaCommand({
addOnly: true,
studentReferenceId: 'STUDENT-0-12345',
academicUnitId: 'BYUH',
educationTestReferenceId: 'SLEP',
dateTaken: '2021-04-09',
sectionData: [
{
sectionReference: 'SLEP_ENGLISH',
score: 35,
testPercentile: 3
}
]
})
const data = await client.send(command)Update a Test Result:
const command = new PutGpaCommand({
addOnly: false,
testResultId: 'EDUCATION_TEST_RESULT-0-12345',
studentReferenceId: 'STUDENT-0-12345',
academicUnitId: 'BYUH',
educationTestReferenceId: 'SLEP',
dateTaken: '2021-04-09',
sectionData: [
{
sectionReference: 'SLEP_ENGLISH',
score: 40,
testPercentile: 5
}
]
})
const data = await client.send(command)Delete a Test Result:
const command = new PutGpaCommand({
addOnly: false,
deleteFlag: true,
testResultId: 'EDUCATION_TEST_RESULT-0-12345',
studentReferenceId: 'STUDENT-0-12345',
academicUnitId: 'BYUH',
educationTestReferenceId: 'SLEP',
dateTaken: '2021-04-09'
})
const data = await client.send(command)See PutEducationTestResultOutputSchema for information about the data that is returned.
workday command: Get_Education_Test_Results
Use this command to get a list of test results associated to an applicant See GetEducationTestResultInputSchema for information about the parameters to include.
const command = new GetEducationTestResultCommand({
// studentReferenceId: 'STUDENT-1-12345',
testResultId: 'EDUCATION_TEST_RESULT-1-00000'
})
const data = await client.send(command)See GetEducationTestResultOutputSchema for information about the data that is returned.
workday command: Submit_Student_Residency
Use this command to note if an applicant is a member of the Church of Jesus Christ of Latter Day Saints. See SubmitStudentResidencyInputSchema for information about the parameters to include.
const command = new SubmitStudentResidencyCommand({
studentReferenceId: 'STUDENT-0-12345',
academicUnitId: 'BYUH',
residencyStatus: 'NONRESIDENT',
residencyReason: 'Member_of_Another_Faith'
})
const data = await client.send(command)See SubmitStudentResidencyOutputSchema for information about the data that is returned.
workday command: Get_Student_Residencies
Use this command to get a list of student residency information for an applicant See GetStudentResidencyInputSchema for information about the parameters to include.
const command = new GetStudentResidencyCommand({
studentReferenceId: 'STUDENT-1-12345'
})
const data = await client.send(command)See GetStudentResidencyOutputSchema for information about the data that is returned.
workday command: Put_Student_Educational_Institution
Use this command to add or update an secondary (high school) or postsecondary (college) institution. See GetStudentEducationalInstitutionInputSchema for information about the parameters to include.
Update an existing institution:
const command = new PutStudentEducationalInstitutionCommand({
addOnly: false,
ceebAptId: '4870',
otherId: '04932',
institutionName: 'Utah Valley University',
levelReference: 'POSTSECONDARY',
// referenceIdList: [] // if this is not included it will default to using the ceebAptId as the reference. If you would like to use the "other_id" as the reference you need to specify that.
})
const data = await client.send(command)Create a new institution:
const command = new PutStudentEducationalInstitutionCommand({
addOnly: true,
// ceebAptId: '',
otherId: '01044',
institutionName: 'OUR LADY HOPE MISSION SEMINARY',
levelReference: 'POSTSECONDARY',
typeReference: 'TWO_TO_FOUR_YEARS'
})
const data = await client.send(command)See PutStudentEducationalInstitutionOutputSchema for information about the data that is returned.
workday command: Get_Student_Educational_Institution
Use this command to get a list of secondary (high school) or postsecondary (college) institutions or query for a specific institution by id. See GetStudentEducationalInstitutionInputSchema for information about the parameters to include.
const command = new GetStudentEducationalInstitutionCommand({})
const data = await client.send(command)See GetStudentEducationalInstitutionOutputSchema for information about the data that is returned.
workday command: Put_Student_Friends_and_Family
Use this command to add or update friend and family data for an applicant. See PutStudentFriendsAndFamilyInputSchema for information about the parameters to include.
const command = new PutStudentFriendsAndFamilyCommand({
addOnly: false,
studentProxyReference: 'STUDENT_PROXY-1-0000',
studentReferenceId: 'STUDENT-0-12345',
nameData: {
first: 'John',
last: 'Doe',
countryReference: 'USA'
},
relationship: 'Father',
phoneData: {
phoneNumber: '123-456-7890',
internationalCode: '+1'
}
})
const data = await client.send(command)See PutStudentFriendsAndFamilyOutputSchema for information about the data that is returned.
workday command: Change_Legal_Name
Use this command to update an applicant's legal name. See ChangeLegalNameInputSchema for information about the parameters to include.
Country ID formats that are accepted are ISO_3166-1_Alpha-2_Code, ISO_3166-1_Alpha-3_Code, and ISO_3166-1_Numeric-3_Code, a Workday ID can be specified instead. Country ID format will default to ISO_3166-1_Alpha-3_Code if none is specified.
The default personReference type is Academic_Person_ID.
Update an applicant's legal name:
const command = new ChangeLegalNameCommand({
personReference: 'STUDENT-6-14088',
countryId: 'USA',
firstName: 'First name',
middleName: 'Middle name',
lastName: 'Last name'
})
const data = await client.send(command)workday command: Change_Home_Contact_Information Use this command to update home contact information. See ChangeHomeContactInformationInputSchema for information about the parameters to include.
Country ID formats that are accepted are ISO_3166-1_Alpha-2_Code, ISO_3166-1_Alpha-3_Code, and ISO_3166-1_Numeric-3_Code, a Workday ID can be specified instead. Country ID format will default to ISO_3166-1_Alpha-3_Code if none is specified.
The default personReference type is Academic_Person_ID.
const command = new ChangeHomeContactInformationCommand({
personReference: 'STUDENT-6-14088',
replaceAddress: false,
replacePhone: false,
replaceEmail: false,
addressInformation: {
deleteFlag: false,
countryId: 'USA',
regionId: 'UT',
addressData: '123 N South Street',
postalCode: '84604',
city: 'Provo'
},
phoneInformation: {
deleteFlag: false,
countryCode: '+1',
phoneNumber: '1111111111'
},
emailInformation: {
deleteFlag: false,
emailAddress: 'aaa@a.com'
}
})
const data = await client.send(command)workday command: Change_Personal_Information
Use this command to update a student's personal information. See ChangePersonalInformationInputSchema for information about the parameters to include.
Country ID formats that are accepted are ISO_3166-1_Alpha-2_Code, ISO_3166-1_Alpha-3_Code, and ISO_3166-1_Numeric-3_Code, a Workday ID can be specified instead. Country ID format will default to ISO_3166-1_Alpha-3_Code if none is specified.
const command = new ChangePersonalInformationCommand({
personReference: 'STUDENT-6-14088',
countryId: 'USA',
religion: 'LDS'