Extend functionality of the Workday HR spoke

  • Release version: Yokohama
  • Updated January 30, 2025
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Extend functionality of the Workday HR spoke

    This guide explains how ServiceNow customers can extend the Workday HR spoke beyond its default capabilities by adding new input and output fields. It focuses on enhancing theLook up Workersaction to meet specific business requirements, such as including the Position Reference ID in requests and retrieving local first and last names from responses.

    Show full answer Show less

    Extending the spoke requires familiarity with the Workday Public Web Services API and the ability to configure the Workday system accordingly.

    Extending the Look up Workers Action

    • Default Action Usage: Initially explore the existing inputs and outputs of the Look up Workers action, which transforms input data pills into Workday request XML and parses the response XML back into output fields.
    • Adding Position Reference ID as Input:
      • Check if Position Reference ID exists as a regular or additional input field; if not, manually create it as a string input variable.
      • Understand the Workday XML structure for Position Reference, which includes a type attribute set to "Position ID" and a value element.
      • Use an existing design pattern from the script section (e.g., organizationReferenceStr) to construct the Position Reference XML node in the SOAP request.
      • Define and integrate this new XML node in the SOAP step, then save and publish the modified action.
      • Test the extension by creating a flow that invokes the action with the Position ID input and verify the generated XML in the execution logs.

    Adding and Modifying Output Fields

    • Retrieve Local First and Last Names:
      • Identify the XPath in the Workday response message for local first name and local last name under the Legal Name data section.
      • Leverage the existing Legal Name design pattern in the Script Parser step to extract these elements into variables.
      • Group these names in a LocalLegalName object and add it to the PersonalData object for easier handling.
      • Create corresponding output variables in the Outputs step, ensuring variable names match those defined in the script.
      • Note that output fields do not have to replicate the exact Workday XML hierarchy but should use correct XPath expressions.
      • Be aware of the maximum number of output elements allowed in a data stream action; remove unneeded outputs if publishing errors occur.
      • Save, publish, and test the action by running a flow with a test worker having local names, verifying correct retrieval via logs.

    Practical Benefits

    • Enables customization of the Workday HR spoke to align with unique organizational data needs without waiting for out-of-the-box updates.
    • Allows ServiceNow workflows to use additional Workday data fields, improving automation accuracy and completeness.
    • Supports synchronous request-response patterns with enhanced data payloads, preserving integration reliability.
    • Provides a tested approach to safely extend and validate Workday spoke actions within ServiceNow Flow Designer.

    Extend the Workday HR spoke beyond the default functionalities, such as adding new input and output fields.

    To extend the Workday HR spoke, ensure that the admin is aware of the Workday Public Web Services API and can configure the Workday system.

    Extend the Look up Workers action

    Look up Workers action available along with the spoke provides most of the required inputs and outputs. Before adding more inputs and outputs to this action, explore ways to use the default spoke action.

    This action transforms the input field data pills in the Workday HR spoke to the associated Workday request XML message and synchronously renders back the Workday response XML message as output field data pills in ServiceNow Workflow Studio. Ensure that you check the Sample request message and Sample response message.

    Modify or extend the default Look up Workers action by creating a copy of it.
    Create copy of the action.
    To add Position Reference ID as part of the request criteria for this action:
    Note:
    • Ensure that you check if the regular input field or the Additional Field input field has the desired input. If none of them have the desired input, perform these instructions to manually create the required input field.
    • The Look up Workers action supports Position Reference ID request element in the Additional Fields input field. For the purpose of demonstration, this field is manually being added in the UI.
    1. Evaluate and understand how Position Reference ID is structured in the Workday request message. The XPath to add a Position Reference ID in the request message is two-folded as per the Workday Public Web Services community post.
      1. Position Reference Type attribute: Get_Workers_Request/Request_Criteria/Position_Reference/@type
      2. The attribute value above, per the Public Web Services doc, is a hard-coded “Position ID.”
        Position ID.
      3. Position Reference Value: Get_Workers_Request/Request_Criteria/Position_Reference
      4. The actual value above is a new input field in the spoke action.
    2. Create an input variable in the Action Input step. Click Create Input and add a simple string type input variable.
      Create the Position Reference ID input.
    3. Create an input variable in the Pre Processing script step.
      1. Click Create Variable.
      2. Add the input variable name with name as position_reference_id.
      3. Drag the Position Reference ID data pill from Input Variables and drop it at the value of the input variable.
        Position Reference ID
    4. Leverage the design pattern of var organizationReferenceStr in the script section.
      1. Create the XML node to match the Workday Get Worker Request message in this example.
      2. Find the appropriate design pattern in the script section accordingly. In this example, this XML node needs to be constructed for Position Reference.
        <bsvc:Position_Reference bsvc:Descriptor="string">
<bsvc:ID bsvc:type="Position_ID">string</bsvc:ID>
</bsvc:Position_Reference>
      3. When the above XML is compared with the similar XML node, Organization Reference is a good candidate to leverage the associated design pattern script from. In the Script section, the associated script snippet is under “var organizationReferenceStr. 
        <bsvc:Organization_Reference bsvc:Descriptor="string">
<bsvc:ID bsvc:type="Organization_ID">string</bsvc:ID>
</bsvc:Organization_Reference>
      4. Leverage the var organizationReferenceStr code snippet to construct the Position Reference XML node accordingly.
        var organizationReferenceStr code snippet.
      5. On the same script, in the var request section, leverage the design pattern, and define an output variable.
        var request section.
    5. Create the Position XML node in the SOAP Step.
      1. Refer to Workday Get Worker Request message and the position reference node accordingly.
        Position reference node.
      2. Save and publish it.
    6. Test the action.
      1. As this is a data stream action, it should be tested using a flow. Create a sample flow with the action in it.
        Test action in a flow.
      2. Provide Position ID and test the flow.
        Provide Position ID.
      3. Open the execution and navigate to SOAP step to check if the updated XML element node with position reference is created.
        Check execution.

    Add and modify output fields of Workday spoke action

    Extend the Workday spoke to retrieve the local first name and local last name.

    1. Evaluate and understand how the local name is structured in the Workday response message.
      • Local First Name: The XPath for this element is Get_Workers_Response/Response_Data/Worker/Worker_Data/Personal_Data/Name_Data/Legal_Name_Data/Name_Detail_Data/Local_Name_Detail_Data/First_Name
      • Local Last Name: The XPath for this element is Get_Workers_Response/Response_Data/Worker/Worker_Data/Personal_Data/Name_Data/Legal_Name_Data/Name_Detail_Data/Local_Name_Detail_Data/Last_Name
    2. Leverage the Legal Name design pattern in the Script Parser step and create the snippet for local legal name.
      var LocalFirstName = xmlDoc.getNodeText(Worker_DataXpath.concat("wd:Personal_Data/wd:Name_Data/wd:Legal_Name_Data/wd:Name_Detail_Data/wd:Local_Name_Detail_Data/wd:First_Name"));
        var LocalLastName = xmlDoc.getNodeText(Worker_DataXpath.concat("wd:Personal_Data/wd:Name_Data/wd:Legal_Name_Data/wd:Name_Detail_Data/wd:Local_Name_Detail_Data/wd:Last_Name"));

        var LocalLegalName = {
            LocalFirstName: LocalFirstName,
            LocalLastName: LocalLastName,
        };
      Legal Name design pattern in the Script Parser step.
    3. Add the LocalLegalName to the PersonalData object.
      LocalLegalName to the PersonalData object.
    4. Create output variables in the Outputs step.
      1. Click Edit Output.
      2. Output fields don't need to follow the exact Workday response message hierarchy. As long as the XPAth from the step 2 follows the right Workday XPath, the spoke action can render the elements accordingly. In this case, adding the Local Legal Name under Personal Data is sufficient.
        Output fields.
        Note:
        String variable name under the Name section must match with the same var name defined in step 2 above.
    5. Save and publish the action.
      Note:
      The Look up Workers action has a maximum number of output elements that a data stream action can have. If any error occurs during the publish of copied action with new output elements, delete a few output elements that are not required and try to publish again.
    6. Test the action.
      1. Ensure that the testing worker subject has the local first name and local last name in Workday.
      2. Create a sample flow, add the action to it, and log the response to verify output elements.
        Test the action.
      3. Provide the associated test worker subject’s Employee ID to test and run the flow.
        Run the flow.
      4. Verify the log and executions to verify if the local first name and local last name are retrieved correctly.
        Verify executions.