FAQ: SAPALink Implementation
- Matthias Rieck
| Question | More Details | Answer |
|---|---|---|
| Which SAP Versions are supported by SAPALink SDK ? | SAPALink is supported by all SAP Systems (including the current ERP6.0 with EHP8). SAP Hana also supports the the ArchiveLink-Protocol (inlcuding the Abap-Stack). | |
| Is it possible to integrate additional documents or metadata from DMS server and makes them available to SAP (eg scanned components from DMS ). How does this works ? | No, not directly. Every Document needs to be known by the SAP System (the process of making a document known to SAP is called "Document Linking"). Every Document Archiving process needs to do two steps: 1). Archive in the DMS-System , 2.) Link to SAP System. (or vice versa). In your specifc scenario you would need to write a tool/connector that take your DMS-Data und Link it into the SAP System (with ContentRepository, Document ID etc.). KGS does not offer a generic solution for that. | |
| High availability : is it possible to have multiple instances of KGSContentServerStorage with a Load balancer like Apache to handle load balancing and failover ? | The KGS ContentServer4Storage is a Java-Servlet running on a Webserver. Servlets can coexist on the same Machine as well as on different machines (they dont need to know each other). Load Balancer are designed to reroute http(s) Requests depending on the load of machines. So definitv YES. Most of our customer uses load balancer. The ContentServer-Address (like http://webserver:port/KGS-Admin/contentserver) is configured in the SAP Transaction OAC0. In case a load balancer is configured, the OAC0 targets the load balancer and this load balancer targets N-ContentServer | |
| Is KGSContentServerStorage compatible HTTPS ? | A similar answer: The Webserver of the Java Servlet handles the Protocol. For a Tomcat for example, you configure https in the "server.xml" (server-level, in the configfolder). Its more or less pass-through. So YES, the KGSContentServer4Storage can also be addresses with https | |
| Extension : componentCreateCold() | createComponent is called First ( with the printlist i think ) and componentCreateCold is called with an ascii textFile. Do you confirm ? How the ASCII text file is generated SAP / KGS ? - What is the format of ascii text , can we have a sample ? | This method is depreciated and is no longer supported in the current release of the KGS ContentServer. |
| Extension : documentKeysSet() | Documentation : This function provides additional keys for the specified document. The Keylist contains meta- data information about the corresponding SAP Object and offers the opportunity to map these information to the Document for an SAPGUI independent search functionality. Example |OBJECT_ID=100019000000152002|SAP_OBJECT=BKPF|AR_OBJECT=FIIINVOICE|KEYNAME1 =KEYVALUE1|KEYNAME2=KEYVALUE2| Question: My understanding is when a document is pushed to the content server a kind of trigger is executed by KGS framework to get associated metadata.
| This understanding is correct. This extension works only with the KGS ContentServer and is not supported by the SAPALink-Standard. The workflow is following: When a document is pushed to the contentserver and in the ContentServer is configured properly for this feature, then a custom SAP Function Module (Z_KGSKEYEXPORT) is triggered. Z_ in SAP means that its a custom Module. So its necessary to have this Z_KGSKEYEXPORT Module "transported" into your SAP System. Its written in ABAP and can be rewritten specific of the customer needs (add additonal Parameters etc.). The Z_KGSKEYEXPORT returns these details as a .idx-file which is stored temporarily on the KGS ContentServer. Depending on your configuation, the KGS ContentServer take these .idx-Files (by time cycle) and processes these (it send exaclty these data [e.g. your Example on the right] to the DMS-System). How you integrate or use this data is up to you. Every request sent to the ContentServer is handled independently and in parallel, so its asynchronous. Every connection (link-open) to the DMS is capable of handling multiple requests, but in case this capability is reached, the KGS ContentServer spawns additional link-open(s). - No ,update or deletion does not trigger the documentKeysSet (delete will send the delete request for the document anyways to the DMS-Backend, so in case you have already a keyset to that document, you have to cleanup these unneeded metadata as well on your DMS System). Specified Metadata is configured / implemented in the SAP Function Module (Z_KGSKEYEXPORT). |
| infoGetLinkVersion() infoGetProductVersion() | - Is there some structured information to suply ? - What is the difference between them ? | The infoLinkVersion refers to your SAPALink.class (in case you extend it or do bugfixes you increment the Version) whereas the infoProductVersion refers to your DMS System Version. There is no structured info to supply, every Vendor is free in syntax as long its a valid String. Keep in mind that these Strings might get delivered via the http(s) Protocol, therefore UTF-8 with no special chars (like &) is highly recommended. Besides, the KGS ContentServer URL-Encode the chars anyways, but in case u are using a non-KGS ContentServer you might get troubles with special chars. |
| ComponentCreate | Documentation : If the document ID is not provided as an input parameter, you have to create a unique doc ID, and return this ID. In the function declaration DocId is set as mandatory - How can we return a docId knowind that the function is void ? | Thats more or less a wrong Documentation. Per ArchiveLink-Standard, its not allowed to create a component without an DocID (its mandatory). Per definition, the ReturnCode for this Request (from the KGS ContentServer) is 400 -> bad Request. So this case is already fetched before it even can occur on DMS Site. Means: the DocID IS mandatory. The Documentation refers to the SAPALink that theoretically allows this (even it does not make sense: Imaging you create a docID and store the component in that document on your DMS. The SAP System will never know about that generated docid and is therefore unknown and unsearchable which result in a zombie-document in your DMS System [Unless you want to access the data without SAP]). Anyways: SAP's ArchiveLink-Protocoll already deny this circumstances which the KGS ContentServer (and SAP ContentServer) handles first. |
| componentGet | Who is responsible of deleting the returned files ? | Thats a bit tricky as well. Because the SAPALink-Protocol is quite old, developers used to work with temp-files. Because of this quite old Interface you have to create the file (if you dont have it already as file) on DMS side and return the absolute path to the file. After the KGS ContentServer delivered the data to the receiver/consumer, he tries to delete the file. So Yes: the ContentServer delete the files afterwards. But its also necessary that the CS has write-Access on the Folder where the DMS create the (tmp)-Files |
| putCert | Available in Document API Test but not in SAPALINK.java . What is the use of this function ? | The putCert is for Security and securing the communication via the Web (https only ensure the transport layer security whereas the putCert(certificate) ensure that only from certificate-aware clients requests are allowed). SAPALink is called from the Contentserver, so the transport to the ContentServer was already successful and allowed (The CS handles the certificate-validation). You only have to ensure the connection (LinkOpen) to your DMS System is secured (or at least it should be). |
| Is there a way to communicate directly with SAP asking for Document or Metadata created between 2 dates ? | Same as before but on Content Server Level | SAP ContentServer / KGS ContentServer etc. are adressed by url or protocol (the SAP ContentServer has a query like serveradress:port:endpoint.dll?create& ....) which is similar to our syntax: serveradress:port:endpoint/contentserver?create& ...). There are several ContentServer out there with different Syntaxes (OpenText,SAP ContentServer, KGS ContentServer,IBM, HP RecordManager|Trim ..). But the parameters are delivered all by url-conform queries [ = ArchiveLink] As mentioned before, ContentServers in SAP are configured in the Transaction OAC0 (which for example also can be read from external with a SAP Connector). Specfic search-requests (like your question regarding every document between Date A and Date B) does not exist in the ArchiveLink/SAPALink-Environment. See the next question regarding search. |
| Search function: why search function is not part of SAPALINK.java ? |
| Search is not provided by SAPALink because SAPALink operate as Interface on DocumentLevel. The Search Logic is integrated on the Client side (e.g. the SAP by itself which can filter and search internally and only ask the Archive/DMS for the result which the User searched for). Search and Find-Logic is Client Side. |
| Is there a Tool de that runs automatically the complete scenarios including LoadTests ? | Actually the DocumentAccessApiTester execute unitary calls | Unfortunately not. The Testsuite is implemented in SAP itself (Transaction RSCMST) and we are rebuilding it on our side right now with Unit-Tests and CICD, but not as a Tool. You might have a look into the SAPALINKTEST.exe (which is in the Package) for Testing your Implementation without the ContentServer. Theres a Button for "Performance Test". After finishing your implementation we can run that Testsuite in our SAP Environment and we will provide the results. |
| ContentServer.cfg | Regarding the entry key = "Security.Default Security" .Default value is set to 2. The documentation explains tha value can be changed to the value of 1. What is the difference ? | Security = 0 -> Off Security = 1 -> On (and directly activated on CS Level without SAP Interaction) Security = 2 -> On (and needs confirmation from SAP Administrator via SAP GUI OAC0) The default is 2 because customers often avoid configuring Tools (especially default-Values). Therefore, a sent Certificate needs to be accepted by the SAP Basis Team/Admin (of a Company). Otherwise everybody would be eigher allowed to Access every Document (with Security 0) via ArchiveLink or be able to send an own Certificate (with putCert) and use this to access Documents without knowledge of the SAP Team (Security 1). |
| Is Barcode Mandatory for certification ? | Barcode is optional for the SAP ArchiveLink Certification process, but it IS possible to extend your certification by this Barcode Option. I also checked our Certificate and it Barcode is marked as Optional but handled like an extended Certification. So: You don’t need to implement that feature for the SAP ArchiveLink Certificate, but if you do, you will be seeing this extension as well in your Certificate. | |
| Technical Critera to be considered in our implementation | There is a Test-Transaction in SAP called RSCMST (we call it traffic light test): This test suite create a lot of ArchiveLink-Requests and ask the ContentServer which translate these requests into SAPALink-Requests. In this Test, every ArchiveLink-Command will be tested. Y ou don’t have to deal with those because the ContentServer will handle these and request your SAPALink-Implementation for those Informations. Your SAPALink.class has already every needed Method. So there are only two requirements to handle: - Completeness (is every SAPALink-Method [except the add-Ons] implemented ?) - Performance. Regarding Performance: SAP has two own Function Modules in order to calculate the throughput. This Module as well as the RSCMST generate Reports. In our last generated Report from SAP a performance targeted was 5 Documents/Second (which is kind of slow). Our KGSStore (with the SAPALink) Implementation did 1000 Documents in 27,34 seconds (so nearly 35 Documents/sec). So obviously there Performance Module do a mass Archiving as well as a Mass DocumentInfo and measure those times. There is no official document (from SAP Side or our Side) regarding the requirements. In the certification Process the SAP does the same we do: We run the RSCMST as well as the Performance Test and if in the Endreport every light is green (therefore Traffic Light 😉 ) SAP mark the Implementation as Certified. The Certification itself is called “BC-AL” HTTP Certificate (See here: https://www.sap.com/documents/2017/01/4812f107-a37c-0010-82c7-eda71af511fa.html) | |
| Version Management | createComponent supplies Version information (eg 0.0.0) which component (SAP ?, Content Server ?) hold the link between different versions of the same component ? what happens with old versions when a new version of a component is created are they deleted ? linked to the new version ? | I Assume you mean "sALVersion". Its not the version of the component, its the ArchiveLink-Version (which is eighter 0046 or 0047). ArchiveLink (and SAPALink) does not version management of Documents or Components. The SAP logic handles these. As an ArchiveVendor you can build it by your own (because you know whenever a component is updated) but version-control does not exist on ArchiveLink-Level / SAPALink. |
| componentPropertySet() with 'FileName' property key | Let's say a component (C1) has been created and its file name is 'PDF1.pdf'. Then we call componentPropertySet() using 'FileName' as property key. Do you confirm that the value of 'FileName' property ( short value is 0 ) is an absolute path ? | Yes, it is an absolute Path (in the docu it says "original filename (including path)". Anyways, keep in mind that this property is irrelevant for retrieving the component via the KGS ContentServer. A request for a specific component and the ContentRepository C1 would look like: http://localhost:8080/KGSAdmin-CS/contentserver?get&pVersion=0047&contRep=C1&docId=D3A97978B9BB4C42AF0A001C5C91799D&compId=PDF1 [without extension, the extension/mime-type is provided by the component-info]. So for all Contentserver-requests the DocID is the unique key. The "componentPropertySet()" with the DMS_COMP_PROPERTY_FILENAME is not mandatory and is therefore not necessary for ContentServer-Requests. But you can use it of course to enrich your component-info with a full-path and retrieve it later with "componentPropertyGet()" |