Implementing the services
This page complements the API contract with what Save2ERP does with each response, and the points not to forget.
Generating Word documents
When it generates a Word document, the target system must write these custom properties into it (document properties, not fields visible in the text):
| Property | Required | Value |
|---|---|---|
S2E_SystemKey | Yes | System name, identical to the name declared in the Save2ERP server configuration (for SAP: logical system, for example P01CLNT100). |
S2E_ObjectType | Yes | Object type, as your services expect it in objectType. |
S2E_ObjectKey | Yes | Object ID, as your services expect it in objectKey. |
S2E_FileName | No | File name suggested to the user, with or without extension (the pane removes the extension and adds the one of the chosen format). |
S2E_TemplateId | No | ID of the Word template, as the template service expects it in templateId: enables designer mode for this document. |
S2E_LabelsShown is reserved to Save2ERP, which writes it into the document while the tag labels are shown: never generate it.
Save2ERP forwards S2E_ObjectType and S2E_ObjectKey as is to your services.
What Save2ERP does with each response
| Target system response | What the user sees |
|---|---|
201 with message | The message, under the title "Success". |
201 without message | The pane's own success message, in its language. |
409 + FILE_ALREADY_EXISTS | The "Duplicate detected" view, with the actions of allowedActions and "Choose another name". |
Other 4xx | The target system's message, as is. Only code and message are passed to the pane. |
401 | Save2ERP renews the token, or asks the user to sign in again. |
5xx, or check without a boolean exists | "Target system error", without details. The response is written to the server logs. |
| No response within the configured timeout (60 s by default) | "The target system is temporarily unavailable". |
404 or 405 without code on the check | The document is sent without checking (service missing). |
Points to watch
- Messages: the
messageis shown as is. Write it in the user's language (for SAP: their logon language), without technical details. - Codes: they drive the pane's behavior, never what is displayed. Only
FILE_ALREADY_EXISTShas a specific meaning; other codes are free. - Allowed actions:
allowedActionsmay depend on the object type. Return the same actions in the check and in a409. - Name comparison: the same rule for both services, otherwise the check does not detect a duplicate that the upload refuses.
- Concurrency: another user may store a file with the same name between the check and the upload. The upload must therefore always check for duplicates itself and answer
409if needed. - Permissions: the services run with the signed-in user's permissions. A user without permission on the object gets
403with an explicit message. existingFile: optional, but helps the user choose between replacing and creating a version.modifiedByis a readable name, not a technical ID.- Size: expect documents up to about 37 MB.
Checklist
- [ ] OAuth2 client registered, with the Save2ERP server's redirect URI and the services' scope.
- [ ]
POST /attachments/check:200response withexistsandallowedActions,422for an unknown object. - [ ]
POST /attachments:201,409+FILE_ALREADY_EXISTS+allowedActions, handling ofonNameConflict. - [ ]
GET /attachments/healthcheck:200response. - [ ] No functional error answered with
404or405. - [ ] Documents generated with the
S2E_…properties. - [ ] Designer mode, if you offer it:
GET /attachments/permissionsandPOST /attachments/readTemplateXml(labels reserved to designers, values allowed to every reader of the object), andS2E_TemplateIdin the templates. - [ ] Tests done with the
/testpage and a real document (see Testing your implementation).