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.
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. 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 | Licence, version, access, maintenance window | Your IT / your Sage 100 partner |
| Setup in Sage 100 | Steps 1–9 | Your IT / your Sage 100 partner |
| Connection in Workist | Step 10 | Workist, together with you |
| Test | Master data and test document | Together |
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.
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 |
| Sage 100 version is known (e.g. 9.0.9) | Determines which package of the Workist API extension is installed — see Supported 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. 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 in particular. |
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.
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 — 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:
- Sign in via Sage ID with the main contact's email address.
- Select the entitlement.
- 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 — you need it in step 10.
Exactly one connection to the Connectivity Gateway is possible per customer installation.
Step 2: Pick the matching package
Download the Workist API extension 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:
- Select the file
100096740.WorkistAPI.….metadatafrom theMETADATAfolder of the matching package. - From version 9.0.9: enable the option Create permissions on import and apply them in the current database.
- 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.
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.
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.
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:
- 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.
- Grant the user the 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.
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 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:
- Open the Extras menu at the top → Externe API-Benutzer verwalten (manage external API users).
- 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.
- Add the Workist client ID as an external API user. Workist does not show up by name in the list, but as this string.
- Assign it to the Workist user from step 7.
- Then restart the application server (step 9). The change only takes effect after that.
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.
- In the Sage Server Manager under Server → Administration → Services, stop the Sage Application Server service.
- Check in Task Manager that all
Sagede.ApplicationServer.IsolationProcess.exeprocesses have ended. End any remaining processes manually. - Start the service again.
- 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)
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 |
| DataSet | WAWI_DB;1 | Database name, semicolon, client number — see DataSet, which also says where to find both values |
| Document type | VVA | Key of the document type — see 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 |
| Quote document type (Sage 100 Offer Document Type) | VPA | Key of the quotes for quote matching, from version 8 — see 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. All three are switched off by default.
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.
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.
- 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.
- Send us the DataSet of the production database. The EntitlementID stays the same.
- 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.
- 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. When updating to version 8, run the permissions script (step 4). Workist then switches the connection to version 8; only then are the features from version 8 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. |
| 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. |
| No access to sales documents | The Workist user lacks permissions. | Check permissions — step 7. |
| 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. |
| 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). Then: that user's permissions in this database, database enabled (step 6), Sage Cloud Connectivity Client service running, entitlement and application server selected (step 1), 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. 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, step 6, step 8 and step 9. |
| 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:
- Zip the entire log folder (default:
C:\SageLog\Default). - 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) | One package per supported Sage 100 version |
| Workist API Installation Guide (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
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.
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.