> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/workday/step-by-step-deployment-guide.md). # Step-by-step deployment guide ### 1. Which data is imported from Workday? The following Workday data is imported: * `Workers` Workers are imported as entities with a configurable set of attributes. Each worker requires a `Worker_ID` (unique identifier) and `Name`, plus any additional attributes you define in the field mapping *(*see *point 4)*. ### 2. Set up the Workday RaaS report The connector pulls data from a Workday Report-as-a-Service (RaaS) endpoint. Before continuing, make sure you have a Workday report that: * Exposes worker data in JSON format under a `Report_Entry` key * Includes `Worker_ID` and `Name` fields for every worker (mandatory) * Includes any additional fields you want to import (e.g. `Department_Name`, `Email`, `Position`) Note down the RaaS endpoint URL of the report. Example: `https://wd2-impl-services1.workday.com/ccx/service/customreport2/your_tenant/your_report` We'll need this later to configure the connection in Elimity. Example report: ```json { "Report_Entry": [{ "Department": "Dept 1", "Email": "user_one@xyz.eu", "Manager": "Manager One", "Name": "User One", "Position": "Position 1", "Worker_ID": "000001", "Worker_Type": "Type 1" }, { "Department": "Dept 2", "Email": "user_two@xyz.eu", "Manager": "Manager Two", "Name": "User Two", "Position": "Position 2", "Worker_ID": "000002", "Worker_Type": "Type 1" }, { "Department": "Dept 3", "Email": "user_three@xyz.eu", "Manager": "Manager Three", "Name": "User Three", "Position": "Position 3", "Worker_ID": "000003", "Worker_Type": "Type 1" }] } ``` ### 3. Configure authentication The connector supports two authentication methods. #### Option A: Basic Authentication 1. Create a dedicated Workday integration user with read access to the report. 2. Note down the `username` and `password`. #### Option B: OAuth 2.0 with Refresh Token 1. Register an OAuth client in Workday with the appropriate scope for the report. 2. Generate a long-lived refresh token for that client. 3. Note down these values: * `Client ID` * `Client Secret` * `Refresh Token` * `Token Endpoint` (e.g. `https://wd2-impl-services1.workday.com/ccx/oauth2/your_tenant/token`) > If both authentication methods are configured, OAuth takes precedence. If neither is fully configured, the import will fail with `MISSING AUTHENTICATION INFORMATION`. ### 4. Define the field mapping and export file #### Part A: Field mapping Decide which fields from the Workday report you want to import into Elimity Insights. For every field, you need: * `workday_id` — the field name as it appears in the Workday report (e.g. `Department_Name`) * `elimity_id` — the attribute id to use in Elimity (e.g. `department`) * `elimity_type` — `string`, `number`, `boolean`, `dateTime` The `Worker_ID` and `Name` fields do **not** need to be in this mapping. They are imported automatically as the entity id and name. They do, however, need to be selected (present) in the Workday report itself. Example mapping: ```json [ { "workday_id": "Department_Name", "elimity_id": "department", "elimity_type": "string" }, { "workday_id": "Email", "elimity_id": "email", "elimity_type": "string" }, { "workday_id": "Manager_ID", "elimity_id": "manager", "elimity_type": "string" }, { "workday_id": "Position", "elimity_id": "position", "elimity_type": "string" }, { "workday_id": "Worker_Type", "elimity_id": "type", "elimity_type": "string" }, { "workday_id": "Age", "elimity_id": "age", "elimity_type": "number" } ] ``` #### Part B: Export file (domain model) It may be easier to define the export file here as well, since the field mapping's "elimity\_id" and "elimity\_type" need to correspond to the attribute types of the worker Entity in Elimity insights itself. The export file is a JSON with the following layout you can copy and edit: ``` { "entityAttributeTypes": [ { "archived": false, "description": "some description (may be empty)", "entityTypeId": "worker", "id": "some id (corresponds to 'elimity_id' field in the field mapping", "name": "some name", "type": "some type (corresponds to 'elimity_type' field in the field mapping" }, { "archived": false, "description": "some description", "entityTypeId": "worker", "id": "some id (corresponds to 'elimity_id' field in the field mapping", "name": "some name", "type": "some type (corresponds to 'elimity_type' field in the field mapping" }, { "archived": false, "description": "some description", "entityTypeId": "worker", "id": "some id (corresponds to 'elimity_id' field in the field mapping", "name": "some name", "type": "some type (corresponds to 'elimity_type' field in the field mapping" } ], "entityTypes": [ { "anonymized": false, "icon": "person", "id": "worker", "plural": "Workers", "singular": "Worker" } ], "relationshipAttributeTypes": [], "relationshipTypes": [] } ``` > **If a field is missing in the configuration file but present in the export file, it will not be imported.** > **If a field is missing in the export file but present in the configuration file, the import will fail with a "no such x" error. You can simply fix this by going to the Worker Entity itself and adding the missing attribute value.** ### 5. Configure the source in Elimity Insights * Go to 'Sources' in the left navigation bar and click 'Add Source'. * Search for 'Custom' and click 'Set Up'. * Click 'Set Up' again and fill in the name of the Source (e.g. `Workday`). * Select 'Upload export file', click 'Continue', and upload the export file for this connector (as defined in step 4B). * Go to the 'Config' tab and click 'Edit'. * Set 'Enable automatic imports via custom gateway' to true and fill in the Gateway URL for the Workday RaaS connector: . Click 'Add configuration value' and add the following values. #### Always required | Key | Type | Where to find it | | ---------- | ------ | ---------------- | | `endpoint` | `Text` | See step 2 | | `config` | `JSON` | See step 4A | #### Basic Authentication (Option A) | Key | Type | Where to find it | | ---------- | ---------- | ---------------- | | `username` | `Text` | See step 3A | | `password` | `Password` | See step 3A | #### OAuth 2.0 (Option B) | Key | Type | Where to find it | | --------------- | ---------- | ---------------- | | `clientId` | `Text` | See step 3B | | `clientSecret` | `Password` | See step 3B | | `refreshToken` | `Password` | See step 3B | | `tokenEndpoint` | `Text` | See step 3B | Now click 'Save and run'. You can monitor progress in the 'Logs' tab; the 'Imports' tab gives more detail if anything goes wrong. ### 6. Troubleshooting Common failure modes and what they mean: | Symptom in logs | Likely cause | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `MISSING AUTHENTICATION INFORMATION` | Neither a complete Basic nor a complete OAuth credential set was provided. Recheck step 3. | | `401 Unauthorized` from the endpoint | Wrong username/password, or expired refresh token. Regenerate credentials per step 3. | | `Duplicate workerID found: for worker: …` | The report returned the same `Worker_ID` twice. Fix the report to ensure uniqueness. | | `KeyError: 'Worker_ID'` / `'Name'` | The report is missing one of the mandatory fields. Add them to the report's selected columns (see step 2). | | Attribute value silently missing | The mapped `workday_id` is absent or empty for that worker; the connector skips empty values by design. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.elimity.com/workday/step-by-step-deployment-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.