Overview
This part is for the team that prepares the target system (the ERP, for example SAP) so that it accepts the documents sent by Save2ERP.
Save2ERP does not depend on a particular ERP: it calls REST services described by a common contract, which each target system implements in its own way. Today, Save2ERP can connect to SAP systems (see Target system: SAP).
What the target system must provide
| Item | Purpose |
|---|---|
| An OAuth2 server and a client registered for Save2ERP | User sign-in, with the user's own permissions ("authorization code" flow with PKCE). |
The check service (POST /attachments/check) | Tells, before sending, whether a file with the same name is already attached to the object, and which actions are allowed. |
The upload service (POST /attachments) | Stores the document as an attachment of the object. |
The test service (GET /attachments/healthcheck) | Lets the administrator check the connection from the /test page. |
| Prepared Word documents | Each generated document carries the S2E_… properties that identify the system and the object (see Preparing Word documents). |
The full contract is described in API contract.
How a document is sent
- The target system generates a Word document, with the
S2E_SystemKey,S2E_ObjectType,S2E_ObjectKeyand, optionally,S2E_FileNameproperties. - The user opens it in Word and clicks the save button in the pane.
- The Save2ERP server calls
POST /attachments/checkwith the object and the file name, while Word reads the document. - If the file does not exist, the server calls
POST /attachmentswithonNameConflict: FAIL. - If it exists, the pane offers the allowed actions (
allowedActions), or applies the option chosen by the user if it is allowed. The document is then sent withonNameConflictset to the chosen action. - The target system answers
201, with or without a message. If it provides a message, the pane shows it as is.
What the Save2ERP server does
- It obtains and renews the user's OAuth2 token, and sends it in the
Authorization: Bearerheader of each call. - It forwards request and response bodies as is: the target system validates the fields and their values.
- It never shows the technical details of a
5xxerror to the user: it writes them to its logs. - It shows the
messageof a functional error (4xx) as is: write it in the user's language.