A Tutorial on Setting Up and Using the Workday SOAP API

Human resources information system (HRIS) solutions help organizations standardize HR tasks, manage employee information, and facilitate accurate record-keeping and reporting. HRIS platforms like Workday are essential for managing various HR processes, from payroll to talent management. Workday provides Simple Object Access Protocol (SOAP) APIs for integration with other systems; however, using these APIs can be challenging due to its complex XML-based structure, rigorous security protocols, and the need for precise configuration and authentication.

The Workday APIs can be used for various tasks, including managing employee data, integrating financial systems, handling recruitment processes, managing time tracking, and facilitating benefits administration. These APIs help automate employee data synchronization to ensure accurate and up-to-date records across systems. Synchronized systems enable real-time onboarding and offboarding workflows, ensuring compliance with HR policies. Additionally, integrating with financial systems enhances payroll processing, reduces errors, and improves efficiency.

In this guide, you will learn how to use Workday APIs with TypeScript and understand how to simplify the integration using the Apideck Unified HRIS API.

Understanding the Workday API

The Workday HRIS platform provides a comprehensive list of SOAP-based APIs that allow access to various HR functions, such as employee management, financial management, recruiting, absence management, and performance management. These APIs use the SOAP protocol, which allows the exchange of structured information between applications using XML data format. Some of the primary use cases for using Workday APIs are as follows:

• Employee management: Workday SOAP APIs can be used to view and modify employee data, such as personal details, roles, compensation, and absence information. This data can be synchronized with other systems, like customer relationship management (CRM), project management, and communication tools, streamlining HR operations and ensuring consistency across all systems.
• Accounting integration: Organizations can leverage Workday APIs to integrate their accounting and payroll systems with Workday. This integration allows automated payroll, deductions, and benefits calculation, reducing manual effort and enhancing overall payroll efficiency.
• HR automation: Workday provides several APIs, such as recruitment, background checks, training, and employee surveys, enabling automation of the onboarding and offboarding processes across systems. This automation streamlines the administrative HR tasks, ensuring timely completion and compliance with company policies.

In the following sections, you'll learn how to work with Workday APIs using TypeScript to fetch employee data, handle XML responses, and implement error handling. You'll also learn how to set up a SOAP client using the strong-soap npm module and use it to make appropriate requests to retrieve employee information. If you like, you can create a Node.js project and install the strong-soap npm module to follow along.

Connecting to Workday Using an ISU

Workday allows you to create an integration system user (ISU) for API integrations, providing secure, limited access to Workday SOAP services.

Integration System Security Group

To create an ISU using the Workday portal, you initially need to create an Integration System Security Group (ISSG). This group allows you to manage integration permissions, ensuring that only authorized operations are allowed. Therefore, this group is essential for maintaining security by restricting access to sensitive actions and data based on specific roles. You can search for the Create Security Group task on the Workday portal and follow the steps to create the group.

Security Permissions

Your ISSG needs permission to interact with the relevant Workday domain, which refers to a set of related security policies and permissions that control access to specific types of data and tasks within the system. Some Workday domains include employee information, payroll, benefits, and recruitment. By configuring domain security policies, you can ensure that only authorized users can perform particular actions and access sensitive information within Workday.

To grant permissions to an ISSG to interact with the desired Workday data domains, do the following:

• Navigate to the View Domain report, find the desired domains, and click Domain > Edit Security Policy Permissions. For Workday HRIS integration, choose the Person Data and Worker Data domains. Refer to this Apideck guide for a comprehensive list of required domains for HRIS integration.
• Add the name of the ISSG and grant GET, POST, and PUT REST API permissions to it.

Integration System User

Once you have an ISSG with the relevant domain permissions, you can create an ISU to interact for secure and dedicated access to Workday APIs. To create an ISU, follow these steps:

• Search for Create Integration System User in the Workday portal and click the matching task when it appears.
• To complete the setup, enter a User Name for the ISU and fill out other details on the form. Optionally, set the Session Timeout Minutes to 0 to prevent session expirations.
• Once the ISU is created, choose Security Profile > Assign Integration System Security Groups to link the desired ISSG with the ISU.

Fetching Employee Data Using SOAP API

Workday provides the Get_Employee API that can be used to fetch employment, personal, and compensation information of a particular employee. The API expects Employee_Reference ID as an input to fetch an employee's data. The Employee_Reference ID is a unique identifier for an employee in the Workday system.

Creating a SOAP Request

To fetch employee data from Workday using SOAP in TypeScript, you create SOAP requests according to the Web Services Description Language (WSDL) definitions provided by Workday. To filter the employee data you want to retrieve, you construct a request payload that includes their security credentials and Employee_Reference. The following script illustrates how this would work:

import { soap } from 'strong-soap';

type SecurityToken = {
    'wsse:UsernameToken': {
        'wsse:Username': string;
        'wsse:Password': string;
    };
};

type EmployeeReference = {
    'wd:ID': {
        'wd:ID': string;
        'wd:type': string;
    };
};

type GetEmployeeRequest = {
    'wsse:Security': SecurityToken;
    'wd:Get_Employee_Request': {
        'wd:Employee_Reference': EmployeeReference;
    };
};

// WSDL URL for Workday Human Resources API
const wsdlUrl = 'https://{your_workday_tenant}.myworkday.com/ccx/service/{your_tenant_name}/Human_Resources/v42.2?wsdl';

// Create a SOAP client
soap.createClient(wsdlUrl, (err: Error, client: any) => {
    if (err) throw err;

    // Define the request arguments
    const requestArgs: GetEmployeeRequest = {
        'wsse:Security': {
            'wsse:UsernameToken': {
                'wsse:Username': '{your_username}',
                'wsse:Password': '{your_password}'
            }
        },
        'wd:Get_Employee_Request': {
            'wd:Employee_Reference': {
                'wd:ID': {
                    'wd:ID': '{employee_id}',
                    'wd:type': 'Employee_ID'
                }
            }
        }
    };

    // Call the Get_Employee operation
    client.Get_Employee(requestArgs, (err: Error, result: GetEmployeeResult) => {
        // Handle the response
    });
});

The preceding code snippet creates a SOAP client and calls the Get_Employee method to fetch employee details. Notice that the requestArgs contains a Security block containing the Workday ISU credentials you created in the previous step.

Handling the Response

The Get_Employee SOAP API returns the Employee_Data element as a response containing all employee data, such as personal info, worker status, compensation, and worker documents. The Workday API returns an XML response, but the strong-soap module parses the XML to JSON, making it easier to work with the output. Here's the updated code snippet that processes the response to print the employee ID and name:

// define types for response
type NameData = {
    First_Name: string;
    Last_Name: string;
};

type PersonalInfoData = {
    Name_Data: NameData;
};

type EmployeeData = {
    Employee_ID: string;
    Personal_Info_Data: PersonalInfoData[];
};

type GetEmployeeResult = {
    Employee_Data: EmployeeData[];
};

client.Get_Employee(requestArgs, (err: Error, result: GetEmployeeResult) => {
    // Handle the response

    // Process the JSON result
    const employeeData = result.Employee_Data[0];
    const { Employee_ID, Personal_Info_Data } = employeeData;

    if (Personal_Info_Data && Personal_Info_Data.length > 0) {
        const { First_Name, Last_Name } = Personal_Info_Data[0].Name_Data;
        console.log(`Employee ID: ${Employee_ID}`);
        console.log(`Name: ${First_Name} ${Last_Name}`);
    } else {
        console.log('No personal information data available.');
    }
});

The preceding code snippet parses the JSON result and logs the employee ID and name to the console. Notice that the Employee_Data object contains the Personal_Info_Data element, which contains the employee's personal information.

Handling API Errors

The Get_Employee script also needs adequate error handling to ensure that it handles missing or null data. An error callback with the Get_Employee API can check for errors before processing the response. In addition, a try-catch block around the response that parses code ensures that your script handles missing data. The following updated code snippet includes these elements to handle errors:

client.Get_Employee(requestArgs, (err: Error, result: GetEmployeeResult) => {
    // Check for errors
    if (err) {
        console.error('Error fetching employee data:', err);
        return;
    }

    // Wrap response processing within a try-catch
    try {
        // Process the JSON result
        const employeeData = result.Employee_Data[0];
        const { Employee_ID, Personal_Info_Data } = employeeData;

        if (Personal_Info_Data && Personal_Info_Data.length > 0) {
            const { First_Name, Last_Name } = Personal_Info_Data[0].Name_Data;
            console.log(`Employee ID: ${Employee_ID}`);
            console.log(`Name: ${First_Name} ${Last_Name}`);
        } else {
            console.log('No personal information data available.');
        }
    } catch (error) {
        console.error('Error processing employee data:', error);
    }
});

Notice that the callback prints the error and returns early if the err object is not null. Additionally, the catch block prints any error encountered while processing the response.

Using the Apideck Unified HRIS API

The Apideck Unified API platform provides enterprise-grade APIs for several use cases with a consistent developer experience, speeding up the API integration process for organizations. It supports a number of connectors for accounting, applicant tracking systems (ATS), CRM, HRIS, e-commerce, point of sale (POS), and more.

The Apideck platform dashboard lets you configure connectors to an application. You can view the active connectors for your application on the Configuration page. Once a connection has been configured, you can use the Apideck Unified API to retrieve or modify data from any of the active connections. Refer to this Apideck guide on connectors to learn more about the supported connectors. You can sign up for a free Apideck account and connect it with Workday to interact with Workday HRIS API services.

In the following section, you will learn how you can use the Apideck Unified API to fetch employee information from Workday. You can create a Node.js project and install the Apideck Node.js npm module to follow this guide.

Setting Up the Connection

The Apideck Unified API can interact with Workday APIs using ISU credentials stored in the Apideck Vault. Vault is a secure service that makes it easier to manage and store sensitive credentials needed for API integrations. To configure the connection, follow these steps:

• Click Vault on the Apideck platform dashboard and click Launch demo under Hosted Vault to open the Vault dashboard.
• On the Vault dashboard and under Manage your integrations, click Workday.
• Fill out the connection details with the ISU user details created in the previous step. For more details, refer to the connection guide.

Initializing the Apideck SDK

The Apideck client enables you to access all the different APIs supported by Apideck using a single interface. You can initialize the Apideck client using the following code snippet:

const { Apideck } = require('@apideck/node')

const apideck = new Apideck({
    apiKey: 'YOUR_APIDECK_API_KEY',
    appId: 'YOUR_APIDECK_APP_ID',
    consumerId: 'YOUR_APIDECK_APP_CONSUMER_ID'
})

Make sure to replace the values for apiKey, appId, and consumerId with actual values. You can find the apiKey and appId under the API keys tab, and you can create a new consumer from the Consumers tab on the Apideck dashboard.

Fetching Employee Information

As discussed in the previous section, working with Workday SOAP APIs involves manually handling requests, responses, and error management, which can make integration complex. Apideck simplifies this process by offering cleaner, developer-friendly interfaces for HRIS API integration. You can use the hris.employeesOne API to fetch an employee's information from Workday as follows:

const fetchEmployeeInfo = async (employeeId: string) => {
    const params = {
        id: employeeId
    }

    try {
        const { data } = await apideck.hris.employeesOne(params)
        console.log('Employee info', data)
    } catch (error) {
        console.error(error)
        return error.json()
    }
}

The employeesOne API expects a request payload with the employee's id as an input.

The Apideck Unified API significantly simplifies Workday integration, allowing seamless fetching, parsing, and manipulation of Workday data without dealing with complex SOAP requests and responses. The Apideck Unified API can also be used for other HRIS platforms, CRM, Accounting, File Storage, and more. The no-data-storage approach of Apideck provides real-time data without persisted caching, ensuring systems stay synchronized and reducing security risks associated with stale or incorrect data.

Conclusion

In this guide, you learned how to integrate the Workday HRIS SOAP API using TypeScript to fetch employee data. Handling the Workday SOAP-based APIs involves complexities, such as implementing API authentication, defining XML payloads, parsing XML responses, and handling errors. The Apideck Unified API can mitigate these challenges, providing access to different HRIS APIs through a unified, developer-friendly interface. The Apideck Unified API platform streamlines API integration with various platforms, including HRIS, CRM, and accounting, enabling you to scale reliably and securely.

Ready to simplify your HRIS integrations? Sign up for Apideck today and start using our Unified HRIS API to streamline your processes: get started with Apideck.