Connect Workday

Connect Workday so the people, teams, open positions and pay in Flowstate follow what HR records in Workday. Hires, leavers, job moves and pay changes reach the forecast without anyone re-keying them.

Setting it up takes your Workday administrator, your integration team and a Flowstate admin. First decide whether Workday is your source of truth. See Get your people data into Flowstate.

How it connects

Workday tells other systems about a change when a business process, such as a hire, completes. Flowstate takes those changes in through its REST API, so the messages go to your integration platform first. If you’d rather not run one, a Flowstate custom integration can read a Workday report on a schedule instead. Use one route for Workday, not both.

Why event-driven is recommended: Workday’s main web services return XML, and a custom integration can only read JSON. Workday’s push subscriptions exist for this job. An integration platform can also set things a scheduled sync can’t, such as a person’s line manager and location.

If your tenant only allows API calls from listed IP addresses, use the event-driven route through your integration platform.

What you need from Workday

• An integration system user for Flowstate, in its own integration system security group. The group needs Get access on the domain security policies that cover the data you sync: workers, organisations, positions and compensation. Workday gives web service operations to no security group by default, so every permission has to be granted.
• For the event-driven route: an integration system to own the push subscription, and your integration platform’s receiving address, user name and password.
• For the scheduled sync: an advanced custom report enabled as a web service that returns JSON, and an API client with a refresh token registered against the integration system user.

Set it up

Your Flowstate contact provides the integration logic for Workday, and works through it with your integration team. There’s no one-click connection.

In Workday

1. Create an integration system user for Flowstate.
2. Add it to an integration system security group.
3. Give the group Get access on the domain security policies for workers, organisations, positions, compensation and, if you use it, recruiting.
4. For the event-driven route: set up a push subscription for the business processes you want to hear about, such as hires, terminations, job changes and compensation changes. Point it at your integration platform’s address. The subscriber must be an integration system.
5. For the scheduled sync:
   1. Build an advanced custom report with the fields in What syncs, and tick Enable as Web Service. Its addresses appear under Web Service View URLs. Check the report can return JSON.
   2. Run Register API Client for Integrations. Tick Non-Expiring Refresh Tokens, choose the Scope (Functional Areas) the report needs, and save the client ID and secret.
   3. On that client, run Manage Refresh Tokens for Integrations, choose the integration system user as the Workday account, and copy the refresh token.

Event-driven: connect your integration platform

1. In Flowstate, go to Settings → Users & Access → API Keys and select Create API Key. Name it after the sync, such as “Workday sync”, and tick view, create and update for employees, contractors, vacancies and teams. See Create and manage API keys.
2. Copy the key and give it to your integration team to store in the integration platform. Keys last 90 days at most, so put a reminder in to replace it.
3. If people are already in Flowstate, your integration team gives each one their Workday ID first. See Adopt people who are already in Flowstate.
4. Your integration team loads everyone once from Workday, leavers included. The platform creates or updates each person in Flowstate by their Workday ID.
5. They switch on the subscription. For each message, the platform reads the worker from Workday and sends the changes to Flowstate. How: Sync people from an HR system with the REST API.

Scheduled sync: set up a custom integration

1. Ask your Flowstate contact to switch on custom integrations.
2. Go to Settings → Integrations, select Browse catalog, open Custom Integrations and select Connect.
3. Select Create Integration. Enter a Name and, in Source System Key, enter workday. You can’t change the key later.
4. Under Credentials, select Add Credential for the client ID, client secret and refresh token, using the key names your Flowstate contact gives you.
5. If people are already in Flowstate, give each one their Workday ID first. See Adopt people who are already in Flowstate.
6. Under Hooks, select Create Hook and choose Pull. Make one hook for each kind of record: teams first, then employees, contractors and vacancies. Paste in the code from your Flowstate contact and select Save Code.
7. Select Test (Dry Run) and check Preview for anyone who’d be created twice.
8. On the Settings tab, turn on Run on schedule, choose an Interval and select Save Code.
9. Turn the hook on with Enable Hook.

More on each step: Manage a custom integration in Settings.

What syncs

A scheduled sync can’t set a person’s location, resource type, line manager or notice date. Set them in Flowstate, or use the event-driven route, which can.

How changes arrive

• Event-driven. A change arrives once its business process completes in Workday and your platform handles the message. Reorganisations can’t be sent as messages, so your platform re-reads organisations on a schedule as well.
• Scheduled sync. Changes arrive on the next run. Each run reads the whole report, so anything missed last time is picked up.
• Effective dates. Workday records both when a change takes effect and when it was entered. For a future-dated hire, leaver or pay change to reach Flowstate early, the report or request has to read ahead of today. Future pay changes show as Scheduled on the person’s Compensation tab until their date.
• Leavers. The termination date becomes the person’s last day. They stay in Flowstate for past months. Keep terminated workers in the report, because someone who drops out of it is left untouched.
• Rehires. A rehire under the same Workday ID updates the same person. On the event-driven route, your platform clears their old end date through the REST API. On a scheduled sync, your technical team clears it through the REST API. See Undo a leaver.
• Edits made in Flowstate. Anything Workday sends is put back the next time that person is updated from Workday. Details Workday doesn’t send stay as you set them.

Check it’s working

• Event-driven: make a test change to a worker in Workday. The change shows on the People, Contractors or Vacancies tab under Resourcing → People and teams. On Settings → Users & Access → API Keys, the key shows recent use.
• Scheduled sync: open the hook’s Execution History tab. The latest run shows Completed, with Records above zero and no failed records in its log.

If something’s not right

Calls to Workday are refused at sign-in. The integration system user’s password has changed, or your tenant’s password rules have expired it, or the refresh token was revoked. Update it in your integration platform. For a scheduled sync, select the pencil icon on the credential and paste the new value.

Some workers or details are missing. The security group doesn’t have Get access on a domain security policy for that data, such as compensation. Grant it in Workday.

A reorganisation didn’t come through. Workday doesn’t send reorganisations as messages. Ask your integration team to re-read organisations on a schedule.

A scheduled sync is refused, though the sign-in details are right. Your tenant only allows API calls from listed IP addresses, and a scheduled sync doesn’t call from a fixed address. Use the event-driven route, with your integration platform’s addresses on the list.

For your technical team

Workday APIs

• SOAP (Workday Web Services). Workday’s directory lists v47.0. Endpoints take the form https://<host>/ccx/service/<tenant>/<Service>/<version>. Workday recommends pinning a version on every request.
• Operations. Get_Workers, Get_Contingent_Worker and Get_Organizations (Human_Resources); Get_Positions (Staffing); Get_Job_Requisitions (Recruiting). Get_Workers returns compensation when the request includes Include_Compensation.
• Paging. Page and Count in Response_Filter. Pin As_Of_Entry_DateTime while paging so the result set doesn’t shift between pages. As_Of_Effective_Date sets the effective date to read as of.
• Changes since a date. Transaction_Log_Criteria_Data with Transaction_Date_Range_Data on Get_Workers.
• Custom reports. An advanced custom report with Enable as Web Service ticked is callable at its Web Service View URLs. Confirm the JSON output format in your tenant.
• REST. Workday’s REST APIs use OAuth and Workday’s configurable security. Check the resources available to your tenant in Workday’s REST directory.
• Auth.
  • An integration system user in an integration system security group with Get on the domain policies. Put includes Get, and isn’t needed.
  • For OAuth, register the client and create a refresh token against the integration system user. Calls then act as that user.

Events

• Put_Subscription (Integrations service) creates a push subscription. Only an Integration System can be the subscriber. Only business-process and Event Lite transaction types can be pushed, not reorganisation activities.
• Endpoint settings: Subscriber_URL (or Use_Deployed_Service_Endpoint), Subscription_User_Name, Subscription_Password and Web_Service_API_Version_Reference. The operation authenticates to the receiver with a user name and password. It has no signature or client-certificate option.
• Check in your tenant whether a message carries the changed data or only a reference to the event. Get_Event_Detail returns an event’s creation date, state and target. Re-read the worker with Get_Workers for current values.

Flowstate

• REST API. https://{tenant}.flowstate.inc/api/v1/org/{orgId} with Authorization: Bearer <key>.
  • There’s no upsert. GET /employees/{workerId}, then POST on 404 or PATCH on 200. Contractors, vacancies and teams work the same way.
  • PATCH /employees/:id sets managerId, geographyId, workTypeId and noticeDate, and { "endDate": null } clears a leaving date.
  • See the recipe and Permissions by endpoint.
• Custom integration.
  • It calls a public HTTPS address and follows no redirects. Responses are capped at 10 MB. Only JSON is parsed; anything else arrives as a string.
  • It can’t present a client certificate or sign an assertion, and doesn’t call from a fixed IP address.
  • Records match on external ID, never email.
  • See Sync people from an HR system and Limits.

Workday documentation

• Workday Web Services directory
• Human_Resources v47.0 and Get_Workers
• Staffing v47.0
• Recruiting v47.0
• Integrations v47.0 and Put_Subscription
• Using Workday Web Services
• Workday integrations overview
• Security for integrations
• Register an API client with a refresh token