Workday Email and Phone writeback

Writeback enables profile sources, such as Okta and Active Directory, to write email and phone number attributes to Workday. You can only use writeback with these two Workday attributes.

There's also a Workday writeback enhancement where Okta makes separate calls to update work and home contact information. This helps ensure that Workday business processes don't block writeback when home contact information for a user is missing. See Configure Workday writeback for home and work contacts.

Before you begin

Set up provisioning for Workday. See Workday

Task 1: Configure Workday

For the writeback feature to work successfully, you need to grant required permissions to the integration system user/System Group and then activate those permissions.

  1. Domain Security Policy Permissions.

    Follow steps a-e (part of step 7) of Grant permissions to an integration system user for the domain "Worker Data: Maintain Contact Information" – Get and Put.

  2. Business Process Security Policy Permissions.

    • Search for bp:contact change, and then edit the Business Process Policy:

      Image that shows choosing Edit from the Business Process Policy menu.

    • Assign the Integration System User's security group created in Create an integration system user in Workday to Initiating Action: Maintain Contact Information (Web Service):

      Image showing the Maintain Contact Information page.

  3. Follow step 7 in Grant permissions to an integration system user to activate the required security policies.

Task 2: Configure Okta

  1. In the Admin Console, go to ApplicationsApplications.

  2. Open your Workday app integration.
  3. Go to the Provisioning tab.

  4. Select To App under Settings. Then, under Workday Attribute Mappings, select Go to Profile Editor.

  5. Click Go to Profile Editor in the Workday Attribute Mappings section.

  6. For each Workday attribute that's supported for writeback, click Add Attribute. Choose the attribute to add and click Save. This is done by discovering attributes from Workday and mapping to the relevant Okta attributes.

  7. Click Refresh Attributes.

  8. Add the required Workday attributes, and then click Save. See Workday Email and Phone writeback for a complete list of available attributes.

    Each attribute has three different data types. The following table explains the data types and uses the Work Email attribute as an example:

    Attribute Name Type Required/Optional Comments Sample Values
    EmailAddressData Work EmailAddress String Required Map to Okta user attribute OktaCustomWorkEmail
    EmailAddressData Work Primary Boolean Required Set this to true when the work email written back to Workday needs to be set as Primary. Default is false. true
    EmailAddressData Work Public Boolean Required Set this to true when the work email written back to Workday needs to be set as Public. Default is false. false

    Workday Contact information has two parameters: Primary and Public:

    Primary: This parameter defines if the contact information is of type Primary or Additional.

    Public: This parameter defines if the contact information visibility is Public or Private.

    Images of the details of the Primary Phone attribute.

    See Resources for a list of the Workday attributes that are currently supported.

  9. Map the newly added attribute to relevant Okta attributes. Click Map Attributes

  10. Select Okta to Workday, map the attributes as shown in the following image, and then click Save Mappings:

    Image of the Workday User Profile Mappings page.

  11. The following examples demonstrate some ways in which you can use Okta Expression Language to parse phone numbers. For example, if user.mobilePhone = +1 (415) 123-4567 x 12345:

    Work Mobile Phone AreaCode: String.substringBefore(String.substringAfter(user.mobilePhone, "(" ), ")" ) -> 415

    Work Mobile Phone InternationalPhoneCode: String.removeSpaces(String.substringBefore(String.substringAfter(user.mobilePhone, "+" ), "(" )) -> 1

    Work Mobile Phone PhoneNumber: String.removeSpaces(String.substringBefore(String.substringAfter(user.mobilePhone, ")" ), "x" )) --> 123-4567

    Work Mobile Phone PhoneExtension: String.removeSpaces(String.substringAfter(user.mobilePhone, "x")) -> 12345

  12. Attribute-Level Sourcing

    In the typical Workday writeback use case, Workday is set as the overall Profile Source. However, to have the email or phone number attributes written back into Workday, configure attribute-level sourcing with Okta, Active Directory, or some other app as Profile Source for those specific attributes. See the following example:

    • Go to DirectoryProfile Editor.

    • Select Okta in the left FILTERS panel, then click Profile.

    • Select Edit.

    • Select the profile source of your choice, then click Save Profile.

    • Go to Attributes, then select CustomFilter.

    • Select User permission and Source priority.

    • Click Save attribute to complete the setup.

Known limitations

  • Format validation/rules for phone number and email:

    • Workday v15: Unlike the Workday user interface, the Workday API doesn't have format validation/rules for phone number or email (for example: Phone number format must be 3 Digits + Optional dash (or dot) + 4 digits).
    • Workday v29 does perform format validation/rules for phone number and email.
  • After Okta sets the Primary Workday attributes, it doesn't set it back to NULL. This is because of a Workday validation rule that doesn't allow NULL values.

  • For compatibility purposes, the following v15 schema attributes are used for writeback:

    • homeEmail
    • homeFax
    • homeMobile
    • homePager
    • homeTelephone
    • workEmail
    • workFax
    • workMobile
    • workPager
    • workTelephone

Supported attributes

S. No

Attribute Name



1 EmailAddressData Home EmailAddress string emailAddressDataHomeEmailAddress
2 EmailAddressData Home Primary boolean emailAddressDataHomePrimary
3 EmailAddressData Home Public boolean emailAddressDataHomePublic
4 EmailAddressData Work EmailAddress string emailAddressDataWorkEmailAddress
5 EmailAddressData Work Primary boolean emailAddressDataWorkPrimary
6 EmailAddressData Work Public boolean emailAddressDataWorkPublic
7 PhoneData Home Fax AreaCode string phoneDataHomeFaxAreaCode
8 PhoneData Home Fax InternationalPhoneCode string phoneDataHomeFaxInternationalPhoneCode
9 PhoneData Home Fax PhoneExtension string phoneDataHomeFaxPhoneExtension
10 PhoneData Home Fax PhoneNumber string phoneDataHomeFaxPhoneNumber
11 PhoneData Home Fax Primary boolean phoneDataHomeFaxPrimary
12 PhoneData Home Fax Public boolean phoneDataHomeFaxPublic
13 PhoneData Home Mobile AreaCode string phoneDataHomeMobileAreaCode
14 PhoneData Home Mobile InternationalPhoneCode string phoneDataHomeMobileInternationalPhoneCode
15 PhoneData Home Mobile PhoneExtension string phoneDataHomeMobilePhoneExtension
16 PhoneData Home Mobile PhoneNumber string phoneDataHomeMobilePhoneNumber
17 PhoneData Home Mobile Primary boolean phoneDataHomeMobilePrimary
18 PhoneData Home Mobile Public boolean phoneDataHomeMobilePublic
19 PhoneData Home Pager AreaCode string phoneDataHomePagerAreaCode
20 PhoneData Home Pager InternationalPhoneCode string phoneDataHomePagerInternationalPhoneCode
21 PhoneData Home Pager PhoneExtension string phoneDataHomePagerPhoneExtension
22 PhoneData Home Pager PhoneNumber string phoneDataHomePagerPhoneNumber
23 PhoneData Home Pager Primary boolean phoneDataHomePagerPrimary
24 PhoneData Home Pager Public Boolean phoneDataHomePagerPublic
25 PhoneData Home Telephone AreaCode string phoneDataHomeTelephoneAreaCode
26 PhoneData Home Telephone InternationalPhoneCode string phoneDataHomeTelephoneInternationalPhoneCode
27 PhoneData Home Telephone PhoneExtension string phoneDataHomeTelephonePhoneExtension
28 PhoneData Home Telephone PhoneNumber string phoneDataHomeTelephonePhoneNumber
29 PhoneData Home Telephone Primary Boolean phoneDataHomeTelephonePrimary
30 PhoneData Home Telephone Public boolean phoneDataHomeTelephonePublic
31 PhoneData Work Fax AreaCode string phoneDataWorkFaxAreaCode
32 PhoneData Work Fax InternationalPhoneCode string phoneDataWorkFaxInternationalPhoneCode
33 PhoneData Work Fax PhoneExtension string phoneDataWorkFaxPhoneExtension
34 PhoneData Work Fax PhoneNumber string phoneDataWorkFaxPhoneNumber
35 PhoneData Work Fax Primary boolean phoneDataWorkFaxPrimary
36 PhoneData Work Fax Public boolean phoneDataWorkFaxPublic
37 PhoneData Work Mobile AreaCode string phoneDataWorkMobileAreaCode
38 PhoneData Work Mobile InternationalPhoneCode string phoneDataWorkMobileInternationalPhoneCode
39 PhoneData Work Mobile PhoneExtension string phoneDataWorkMobilePhoneExtension
40 PhoneData Work Mobile PhoneNumber string phoneDataWorkMobilePhoneNumber
41 PhoneData Work Mobile Primary boolean phoneDataWorkMobilePrimary
42 PhoneData Work Mobile Public boolean phoneDataWorkMobilePublic
43 PhoneData Work Pager AreaCode string phoneDataWorkPagerAreaCode
44 PhoneData Work Pager InternationalPhoneCode string phoneDataWorkPagerInternationalPhoneCode
45 PhoneData Work Pager PhoneExtension string phoneDataWorkPagerPhoneExtension
46 PhoneData Work Pager PhoneNumber string phoneDataWorkPagerPhoneNumber
47 PhoneData Work Pager Primary boolean phoneDataWorkPagerPrimary
48 PhoneData Work Pager Public boolean phoneDataWorkPagerPublic
49 PhoneData Work Telephone AreaCode string phoneDataWorkTelephoneAreaCode
50 PhoneData Work Telephone InternationalPhoneCode string phoneDataWorkTelephoneInternationalPhoneCode
51 PhoneData Work Telephone PhoneExtension string phoneDataWorkTelephonePhoneExtension
52 PhoneData Work Telephone PhoneNumber string phoneDataWorkTelephonePhoneNumber
53 PhoneData Work Telephone Primary boolean phoneDataWorkTelephonePrimary
54 PhoneData Work Telephone Public boolean phoneDataWorkTelephonePublic