Skip to content

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):

PropertyRequiredValue
S2E_SystemKeyYesSystem name, identical to the name declared in the Save2ERP server configuration (for SAP: logical system, for example P01CLNT100).
S2E_ObjectTypeYesObject type, as your services expect it in objectType.
S2E_ObjectKeyYesObject ID, as your services expect it in objectKey.
S2E_FileNameNoFile name suggested to the user, with or without extension (the pane removes the extension and adds the one of the chosen format).
S2E_TemplateIdNoID 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 responseWhat the user sees
201 with messageThe message, under the title "Success".
201 without messageThe pane's own success message, in its language.
409 + FILE_ALREADY_EXISTSThe "Duplicate detected" view, with the actions of allowedActions and "Choose another name".
Other 4xxThe target system's message, as is. Only code and message are passed to the pane.
401Save2ERP 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 checkThe document is sent without checking (service missing).

Points to watch ​

  • Messages: the message is 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_EXISTS has a specific meaning; other codes are free.
  • Allowed actions: allowedActions may depend on the object type. Return the same actions in the check and in a 409.
  • 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 409 if needed.
  • Permissions: the services run with the signed-in user's permissions. A user without permission on the object gets 403 with an explicit message.
  • existingFile: optional, but helps the user choose between replacing and creating a version. modifiedBy is 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: 200 response with exists and allowedActions, 422 for an unknown object.
  • [ ] POST /attachments: 201, 409 + FILE_ALREADY_EXISTS + allowedActions, handling of onNameConflict.
  • [ ] GET /attachments/healthcheck: 200 response.
  • [ ] No functional error answered with 404 or 405.
  • [ ] Documents generated with the S2E_… properties.
  • [ ] Designer mode, if you offer it: GET /attachments/permissions and POST /attachments/readTemplateXml (labels reserved to designers, values allowed to every reader of the object), and S2E_TemplateId in the templates.
  • [ ] Tests done with the /test page and a real document (see Testing your implementation).