# Sage 100 – Installation This page walks you step by step through setting up the Workist connection in your Sage 100. What the connector reads and writes, and which details Workist needs from you, is described under [Sage 100 Connector](/en/docs/data-exchange/connectors/sage-100.md). ## Process at a glance The setup is usually carried out by your IT or your Sage 100 partner — mostly together with Workist in one session. Your partner can also run steps 1–9 alone and then send us the [details from step 10](#step-10-create-the-connection-in-workist). Allow about an hour for the installation, plus the application server restart. You do not need to set up any endpoints by hand — they come with the Workist API extension. Afterwards we check together that master data arrives and that a test document lands correctly in your Sage 100. | Phase | Steps | Who | | --- | --- | --- | | [Preparation](#preparation) | Licence, version, access, maintenance window | Your IT / your Sage 100 partner | | [Setup in Sage 100](#setup-in-your-sage-100) | Steps 1–9 | Your IT / your Sage 100 partner | | [Connection in Workist](#step-10-create-the-connection-in-workist) | Step 10 | Workist, together with you | | [Test](#step-11-check-the-connection) | Master data and test document | Together | :::tip Start with the test environment Set up the connection on a test database of your Sage 100 first. Only once master data and test documents run cleanly there is the production database connected — see [Switching to production](#switching-to-production). ::: ## Preparation Clarify these points before the setup session. If one of them is missing, the setup usually stalls at exactly that point. | Item | Why | | --- | --- | | **3rd Party Gateway licence** is in place | Without it the Sage 100 API cannot be reached from outside — see [Licence](#prerequisite-3rd-party-gateway-licence) | | **Sage 100 version** is known (e.g. 9.0.9) | Determines which package of the Workist API extension is installed — see [Supported versions](/en/docs/data-exchange/connectors/sage-100.md#supported-sage-100-versions) | | **Main contact's Sage ID** is at hand | Used to connect the Connectivity Gateway (step 1) and to allow Workist as an external API user (step 8). With two-factor authentication, the main contact must be available during the setup. | | **Administrative access** to Server Manager, AppDesigner, Sage 100 Administrator and SQL Server Management Studio | All steps take place on the Sage 100 server | | **Maintenance window** is scheduled | The application server must be restarted; no one can work in Sage 100 during that time (step 9) | | **Document type** is decided | Determines which document Workist orders become in Sage 100 — see [Document type](/en/docs/data-exchange/connectors/sage-100.md#document-type). Your sales or order processing team makes this decision, not the partner. If Workist should use a document type of its own, such as a pre-document without effect, your partner must create it before the test. | | **Other API integrations** are known | If another product already uses the External API, the installation affects that integration — see the note below. The existing setup does not cover Workist: every step is still needed, [step 8](#step-8-allow-workist-as-an-external-api-user) in particular. | :::warning Plan the restart around daily operations Restarting the application server (step 9) interrupts all Sage 100 users. In addition, a file of the extension cannot be replaced while Sage 100 is using it. With more than a handful of users it is advisable to run steps 2–9 in a maintenance window outside business hours. ::: :::warning Other API integrations on the same server If other integrations via the Sage 100 API are active, they may not work correctly between the metadata import (step 3) and the restart (step 9). Run import and restart back to back in the same maintenance window. Because only one connection to the Connectivity Gateway is possible per installation, all integrations share that connection — talk to us beforehand if another product already uses it. ::: ### Prerequisite: 3rd Party Gateway licence Using the Sage 100 API externally requires a **3rd Party Gateway** licence — Sage recommends one licence per customer. On licensing, Sage registers your main contact's email address together with a customer ID — the [EntitlementID](/en/docs/data-exchange/connectors/sage-100.md#entitlementid) — in the Entitlement Service. You obtain the licence through your Sage 100 partner. Order the licence early — in our experience, activation by Sage takes a few days. For activation, Sage asks about the application: Workist is a web application that communicates **machine-to-machine** with your Sage 100. While you are at it, check which email address Sage has registered for your entitlement — step 1 signs in with exactly that address. ## Setup in your Sage 100 The official guide to the Sage Connectivity Gateway can be found in the Sage documentation: Setting up Sage 100 – Sage Documentation ↗ ### Step 1: Connect the Connectivity Gateway In the Sage 100 Server Manager under **External API** → **Establish connection**: 1. Sign in via Sage ID with the main contact's email address. 2. Select the entitlement. 3. Select the application server that requests are forwarded to. If needed, configure a proxy in the same dialog. Afterwards, **External API** → **Configuration** shows the [EntitlementID](/en/docs/data-exchange/connectors/sage-100.md#entitlementid) — you need it in step 10. :::note One connection per installation Exactly **one** connection to the Connectivity Gateway is possible per customer installation. ::: ### Step 2: Pick the matching package Download the [Workist API extension](#downloads) and unpack it. It contains a separate folder for each supported Sage 100 version, each with the subfolders `METADATA`, `DLLS` and `SKRIPTE`. Use **only** the folder that matches your Sage 100 version — the packages are not interchangeable and not backward compatible. What counts are the first three digits of the version (9.0.X). The folders are named, for example, `Workist-170163136-9.0.10.3`; the last digit is the revision of the extension, not your patch level. For Sage 100 9.0.10.4, use the folder for 9.0.10. ### Step 3: Import the metadata In the AppDesigner under **Metadata** → **Import**: 1. Select the file `100096740.WorkistAPI.….metadata` from the `METADATA` folder of the matching package. 2. From version 9.0.9: enable the option **Create permissions on import and apply them in the current database**. 3. Confirm the dialog. The import is only complete once the metadata index has finished building. In the overview, the Workist extension appears under partner number **96740**. ### Step 4: Apply the permissions How the extension's permissions get into your databases depends on the version: | Sage 100 version | Procedure | | --- | --- | | 9.0.9 and later | Created during the metadata import (step 3). For further databases, apply them there as well after the import. From version 8 of the extension, also run the script — see below. | | 9.0.8 | Run the script `…-Berechtigungen.sql` from the `SKRIPTE` folder in SQL Server Management Studio on every affected database. | From version 8 of the extension, run the script `2026-10-06-Berechtigungen.sql` from the `SKRIPTE` folder **on every Sage 100 version**: version 8 adds new endpoints for cost centres and cost units (area `API.Rewe`). If permissions are set to **Detailed**, also authorise the Workist user for this area — see [Required permissions](#required-permissions). ### Step 5: Create the Workist fields Run the script `…-UpdateUserFields-Workist.sql` from the `SKRIPTE` folder in SQL Server Management Studio on every database Workist should access. It creates the two fields that make Workist documents traceable — see [Additional fields in your tables](/en/docs/data-exchange/connectors/sage-100.md#additional-fields-in-your-tables). After running it, it takes a moment until Sage 100 has rebuilt its cache and the fields are available. Both script names carry a date prefix, such as `2026-06-29-UpdateUserFields-Workist.sql`. If the `SKRIPTE` folder is empty, contact us. :::warning Not part of the metadata import This script is **not** run by the metadata import and is not listed in Sage's installation guide. Without this step the fields are missing. ::: ### Step 6: Enable the databases In the Sage 100 Administrator, enable every database Workist should reach **explicitly** for connectivity. A database that is not enabled is invisible to Workist — even when every other step is done. ### Step 7: Create and authorise the Workist user In the Sage 100 Administrator: 1. Create a Sage 100 user for Workist. Give it a recognisable name (such as "Workist") so it stays clear which partner service the user belongs to — the name itself does not matter to Workist. 2. Grant the user the [required permissions](#required-permissions) in the **API** area. If permissions in your Sage 100 are set to **Detailed** rather than **All**, they must be set per user or group. This user's permissions determine what Workist may read and create in your Sage 100. If your **Public** group already denies the whole **API** area, grant the permissions through a group of their own and assign the Workist user to it. This user is a technical user — separate from the main contact's personal Sage ID from step 1. Workist needs **no** password for it: do not send us any Sage login details. :::tip Narrowing down missing permissions If the connection check reports that access to sales documents is not allowed, it is almost always down to this user's permissions. Check the areas in the [Required permissions](#required-permissions) table first. ::: ### Step 8: Allow Workist as an external API user Only this step links Workist to the user from step 7. Without it, Sage 100 rejects every request from Workist with *access denied* (HTTP 401), even when every other step is done. Sage's guide shows it only in a screenshot, so it is easy to miss. In the Sage 100 Administrator: 1. Open the **Extras** menu at the top → **Externe API-Benutzer verwalten** (manage external API users). 2. Sign in with the Sage account the Connectivity Gateway is connected with (step 1). If this account uses two-factor authentication, the main contact must be available for it. 3. Add the [Workist client ID](#workist-client-id) as an external API user. Workist does not show up by name in the list, but as this string. 4. Assign it to the Workist user from step 7. 5. Then restart the application server (step 9). The change only takes effect after that. :::warning An existing API integration does not replace this step Every product that uses the Sage 100 API signs in with its own client ID. If the list already contains another external API user — for a web shop or another partner product, for example — that entry does not cover Workist. The Workist client ID has to be added as well. ::: ### Step 9: Restart the application server The extension's files are only distributed and the new endpoints only become active with the restart. 1. In the Sage Server Manager under **Server** → **Administration** → **Services**, stop the **Sage Application Server** service. 2. Check in Task Manager that all `Sagede.ApplicationServer.IsolationProcess.exe` processes have ended. End any remaining processes manually. 3. Start the service again. 4. Check that these files are present in the Shared directory of your Sage 100 (default: `C:\Program Files (x86)\Sage\Sage 100\9.0\Shared`): | File | Check | | --- | --- | | `PSDev.Sage100.Workist.BusinessLogic.dll` | File version matches the Sage 100 version | | `PSDev.Sage100.Workist.Core.dll` | File version matches the Sage 100 version | | `PSDev.Sage100.Workist.DataAccess.dll` | File version matches the Sage 100 version | | `PSDev.Sage100.Workist.RealTimeData.dll` | File version matches the Sage 100 version | | `Newtonsoft.Json.dll` | Present | The file version is made up of the major, minor and build of your Sage 100 plus the extension's revision — for example `9.0.9173.1` for Sage 100 9.0.8: | Sage 100 version | Major.Minor | Build | | --- | --- | --- | | 9.0.8 | 9.0 | 9173 | | 9.0.9 | 9.0 | 9670 | | 9.0.10 | 9.1 | 268 | | 9.0.11 | 9.1 | 866 | If the files are missing after the restart, copy them from the `DLLS` folder of the matching package into the Shared directory. If a file — usually `Newtonsoft.Json.dll` — is in use, it can only be replaced once Sage 100 and the application server have been stopped. Then start the application server again. ### Checklist before handing over to Workist Tick off these items before you send us the details for step 10: - [ ] Connectivity Gateway connected, EntitlementID noted (step 1) - [ ] Package for your Sage 100 version imported, permissions and Workist fields applied (steps 2–5) - [ ] Every database enabled for Workist (step 6) - [ ] Workist user created and authorised in the **API** area (step 7) - [ ] Workist client ID entered under **Externe API-Benutzer verwalten** and assigned to the Workist user (step 8) - [ ] Application server restarted **after** step 8, DLLs present (step 9) - [ ] Document type created and its key known ([Document type](/en/docs/data-exchange/connectors/sage-100.md#document-type)) ## Step 10: Create the connection in Workist With the following details Workist creates the connection to your Sage 100 — in Workist under **Settings** → **Integrations** → **Sage 100**: | Detail | Example | Notes | | --- | --- | --- | | **Name** | `Sage 100 Test` | Free text. A name that tells test and production apart makes the later switch easier. | | **EntitlementID** | – | From step 1 — see [EntitlementID](/en/docs/data-exchange/connectors/sage-100.md#entitlementid) | | **DataSet** | `WAWI_DB;1` | Database name, semicolon, client number — see [DataSet](/en/docs/data-exchange/connectors/sage-100.md#dataset), which also says where to find both values | | **Document type** | `VVA` | Key of the document type — see [Document type](/en/docs/data-exchange/connectors/sage-100.md#document-type) | | **Channels** | – | The Workist channels whose orders are transferred into this Sage 100 | | **Version of the extension** (*Sage 100 API Version*) | `8` | Installed version of the Workist API extension — see [Version](/en/docs/data-exchange/connectors/sage-100.md#version-of-the-workist-api-extension) | | **Quote document type** (*Sage 100 Offer Document Type*) | `VPA` | Key of the quotes for quote matching, from version 8 — see [Quote document type](/en/docs/data-exchange/connectors/sage-100.md#quote-document-type) | From version 8, you also set the price check, creating documents as drafts and writing by agents in the same connection — see [Features from version 8](/en/docs/data-exchange/connectors/sage-100.md#features-from-version-8-of-the-extension). All three are switched off by default. :::warning Write the DataSet exactly as it appears in Sage 100 Database name and client number are separated by a **semicolon**, without spaces. A typo in the database name or the wrong separator means Workist cannot connect to the database. ::: ## Step 11: Check the connection ### Master data Once the connection has been created, Workist triggers the first master data import. After that, Workist refreshes the master data automatically **once a day**. You can see the status in Workist under **Settings** → **Integrations** → **Sage 100**: the connection status, the time of the last master data update and — while an import is running — a notice that a data update is in progress. Reload the page to see the current state. The same page also lets you trigger an update manually. Depending on the amount of data, the first import can take a while. Afterwards, check under **Manage master data** in the relevant channel that the number of customers, delivery addresses and articles is plausible. :::note Changes in Sage 100 reach Workist with the next import Anything you change in Sage 100 during the day — such as a newly created article — is only available in Workist after the next master data update. ::: ### Test document Send a real order through Workist as a test and complete it. Then check in Sage 100: - Was the document created with the configured document type? - Are customer, order number, articles and quantities in the right fields? - Was a delivery address carried over? If the order does not state one, Sage 100 applies the customer's default delivery address. Test documents are created in the **test database** — look for them there, not in the document overview of your production database. Delete them after the test. A dedicated test document type without further effect also makes test documents easy to spot. Workist only creates a document once a **customer number** has been determined. If Sage 100 rejects the document, Workist shows the message from Sage 100 on the document. After the correction, the transfer can be triggered again directly on the document — you do not need to send the document to Workist again. ## Switching to production Once master data and test documents run cleanly in the test environment, the production database is connected. Plan a short session of its own with your Sage 100 partner and Workist for this. 1. Run steps 4–7 on the production database, if not already done: the database must be enabled, and the Workist user needs the same permissions there as in the test database. 2. Send us the DataSet of the production database. The EntitlementID stays the same. 3. Workist creates a connection with the production database's DataSet or switches the existing one over. We make this switch in Workist — nothing further is needed in Sage 100. 4. From now on, your staff forward orders to the address of the **production** channel, no longer to the test channel. If you have no separate test system, a copy of the database on the production application server is sufficient — provided steps 4–7 were run on the copy as well. ## New version of the Workist API extension When Workist extends the connector, you receive a new version of the extension. Install it the same way as the first version — steps 2–5 and 9, including the scripts and the restart in a maintenance window. The AppDesigner shows which version is installed. Let us know once the new version is installed. Version 8 adds the document fields save status, document date, matchcode, memo, cost centre and cost unit — see [Field reference](/en/docs/data-exchange/connectors/sage-100-fields.md#further-fields-from-version-8-of-the-extension). When updating to version 8, run the permissions script ([step 4](#step-4-apply-the-permissions)). Workist then switches the connection to version 8; only then are the [features from version 8](/en/docs/data-exchange/connectors/sage-100.md#features-from-version-8-of-the-extension) available. ## After a Sage 100 update The extension is tied to your Sage 100 version. If you plan a Sage 100 update, the extension is part of it: after the update, install the package for the **new** version again (steps 2–5 and 9). If no package is available yet for the new version, talk to us before the update. ## Troubleshooting | Message or behaviour | Cause | Fix | | --- | --- | --- | | *Es konnte kein Handler für ENDPUNKT ermittelt werden.* (No handler could be determined for ENDPOINT) | The extension's endpoints or the change from step 8 are not yet active in the application server. | Restart the application server — [step 9](#step-9-restart-the-application-server). | | *Websocket client 'NUMMER' has not been connected to the WebSocket Server.* | The **Sage Cloud Connectivity Client** service is not running, or the External API is not configured. | Start the service; check the External API in the Server Manager — [step 1](#step-1-connect-the-connectivity-gateway). | | No access to sales documents | The Workist user lacks permissions. | Check permissions — [step 7](#step-7-create-and-authorise-the-workist-user). | | *Der Wert … ist für das Feld Belegtyp-Kennzeichen nicht gültig.* (The value … is not valid for the document type key field) | The configured document type does not exist in this client. | Check the document type key — [Document type](/en/docs/data-exchange/connectors/sage-100.md#document-type). | | *Der Wert … ist für das Feld … nicht gültig.* (The value … is not valid for the field …, e.g. for the delivery terms) | Sage 100 only accepts values stored in your client — in exactly that spelling. | Create the value in Sage 100 or align the spelling. | | Access denied (HTTP 401 or 403), on first connecting or after switching to the production database | Workist's sign-in is rejected — with HTTP 401, usually because Workist is not allowed as an external API user. | Check first: client ID entered under **Externe API-Benutzer verwalten** and assigned to the Workist user, application server restarted afterwards ([step 8](#step-8-allow-workist-as-an-external-api-user)). Then: that user's permissions in **this** database, database enabled ([step 6](#step-6-enable-the-databases)), **Sage Cloud Connectivity Client** service running, entitlement and application server selected ([step 1](#step-1-connect-the-connectivity-gateway)), other products on the same gateway. | | Database access error for contacts only, all other data arrives | Bug in older versions of the extension with user-defined fields of the address table | Install the current version of the extension — see [New version](#new-version-of-the-workist-api-extension). Customers, articles and documents are not affected. | | Document rejected because a value is too long | Sage 100 limits field lengths — the name of a delivery address, for example, is limited to 50 characters. | Shorten the value in the document and trigger the transfer again. | | A different delivery address does not arrive in Sage 100 | Without a name, Sage 100 does not take over a different delivery address. | Add the delivery address name in the document. | | Documents are rejected, or the last master data update is several days old | The API service on your Sage 100 server has stopped responding. | Restart the **Sage Application Server** and **Sage Cloud Connectivity Client** services. Keep an eye on the time of the last master data update in Workist — it shows early when the connection is stuck. | | Connection fails although every step is done | DataSet misspelled, database not enabled, Workist not allowed as an external API user, or application server not restarted yet. | Check the [DataSet](/en/docs/data-exchange/connectors/sage-100.md#dataset), [step 6](#step-6-enable-the-databases), [step 8](#step-8-allow-workist-as-an-external-api-user) and [step 9](#step-9-restart-the-application-server). | | A file in the Shared directory cannot be replaced | The file is in use. | Stop Sage 100 and the application server, replace the file, start the application server. | ### Logs for support The Sage 100 API does not pass the exact cause of an error to the outside — it is in your Sage 100's TraceLog. If we or Sage need a log for the analysis: 1. Zip the entire log folder (default: `C:\SageLog\Default`). 2. Tell us the approximate time of the error. If no log file has been written on the day in question yet, restart the **Sage Logging Service** first. This is also possible during normal operation. ## Reference ### Downloads | File | Contents | | --- | --- | | [Workist API Extension version 8 (ZIP)](/files/sage-100/workist-api-erweiterung.zip) | One package per supported Sage 100 version | | [Workist API Installation Guide (PDF)](/files/sage-100/workist-api-installationsanleitung.pdf) | Sage's guide: metadata import, file distribution, troubleshooting | ### Workist Client ID Workist authenticates against your Sage 100 system via **Sage ID** using OpenID Connect, in machine-to-machine (M2M) mode. The Workist client ID is: `WPw9RlvT5I5XCX25kAsOKB3REYv98FRq` :::note The client ID is not a password The client ID is a public application identifier and is identical for all Workist customers. There is no password and no client secret for you to enter. In M2M mode, the client ID takes **the place of the Sage ID email address** as the identity of the calling system. It therefore goes where the Sage account is entered for an interactive user – not as a password, not as a licence key, and not as an entry in the Server Manager. Where exactly is described in [step 8](#step-8-allow-workist-as-an-external-api-user). ::: ### Required permissions The permissions relevant to the API are listed in the Sage 100 Administrator under the **API** area: | Area | Permissions | | --- | --- | | `API.VK` | Sales document, sales document item, sales document item stock, sales article pricing | | `API.EK` | Purchase document, purchase document item, purchase document item stock | | `API.Artikel` | Articles, storage location stock | | `API.Kunden` | Customers | | `API.Ansprechpartner` | Contacts | | `API.Lager` | Warehouse search | | `API.Lieferanschriften` | Delivery addresses | | `API.Projekte` | Projects | | `API.Rewe` | Search cost centre, search cost unit (from version 8) | The API extension additionally creates permissions under the **SData services** area — master data, transaction data and real-time data.