Introduction
tia® Web Service provides you with an easy to use standard archive interfaces available for all applications allowing you to use ArchiveLink® outside of an SAP system. The tia® Web Service fully encapsulates the ArchiveLink® protocol and reduces it to simple commands such as ‘get’, ‘put’, and ‘delete’. Communication via this network is secured with encryption and certificates, eliminating the possibility of unauthorised access Functional overview of tia® Web Service
System requirements
Installation
Licensing
Configuration
Webservice API
Some of the service methods require or return a structure which is known as a Document. This structure is defined as follows. The tia Webservice exposes the following APIs. Service name Service method Description Parameter Description Return codes / Return Type Availability ServiceCheck String ServiceCheck(String ApplicationName, String UserName, String seckey) This API may be used in order to check whether a service is available for an application. This API returns the application name. Please note: In case an application is configured and deactivated, it will still return the application name. ApplicationName: Application which is mapped against a specific Content Server. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. Returns a string indicating whether web service is availble for the specified application name. API available since version 1 serverInfo int ContentServerInfo(String ApplicationName, String UserName, String seckey) API may be used to check whether configured content server is available. This API is equivalent to an SAP ArchiveLink Server Info-command. It returns a response code. Please refer to SAP Content Server HTTP Interface guide for more details regarding the response code. ApplicationName: Application which is mapped against a specified Content Server. UserName: Username which is provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 info Document ContentServerDocInfo(String ApplicationName, Document document, String UserName, String seckey) The API may be used in order to fetch information regarding a certain Document and its respective components. This API returns a Document structure which should be implemented by the client application. Please refer to https://kgs-software.atlassian.net/wiki/pages/createpage.action?spaceKey=SUPPORT&title=Structures%20used%20in%20Webservice%20%28WA%29 for additional information. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID UserName (Optional) Component ID (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for info-Requests). Returns a document structure containing the following. DocId Component ID ( Please note: In case the document contains multiple components, only one component Id will be returned) Component size Doc Type mapped against MimeType HTTP Return code Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 delete int ContentServerDocDel(String ApplicationName, Document document, String UserName, String seckey) This API may be used in order to delete the specified document. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID (Optional) Component ID (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for delete-Requests). Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 get Document ContentServerDocGet(String ApplicationName, Document document, String UserName, String seckey) This API may be used in order to fetch the specified document. In case no component was specified the default data component will be fetched. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID: The document ID which was given to the document when it has been archived. (Optional) CompID: The component ID which should be retrieved from the document. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for delete-Requests). Returns a document structure containing the following: An array of bytes containing the component The size of the component The document type mapped against a mime type. The HTTP Return code. Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 MDocument ContentServerDocGetv2(String ApplicationName, MDocument recvDoc, String UserName, String seckey, Boolean ConvertToPdf, String Watermark) This API may be used in order to fetch the specified document. In case no component was specified the default data component will be fetched. In addition to the features from version 1 this API also allows you to convert a component during the retrieval process to Pdf as well as placis a watermark on the generated Pdf document, if specified. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID: The document ID which was given to the document when it has been archived. (Optional) CompID: The component ID which should be retrieved from the document. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for delete-Requests). (Optional) ConvertToPdf: Defines whether a component should be converted to a Pdf file. This flag applies to each component, whose content type is either JPEG JPG TIF TIFF (Optional) Watermark: Defines whether a Pdf should be marked with the specified watermark text. Returns a document structure containing the following: An array of bytes containing the component The size of the component The document type mapped against a mime type. The HTTP Return code. Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 2 create int ContentServerDocCreate(String ApplicationName, Document document, Boolean Async, String UserName, String seckey) This API may be used in order to create a document. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID: The document ID which was given to the document when it has been archived. (Optional) CompID: The component ID which should be retrieved from the document. In case no component Id was provided, data will be used as component Id. DocType: The type of the document mapped against a mime type. Async: The Async boolean defines, whether the received document should be placed in the specified Working Directory. Asynchronous requests may be used best, when tia Document Router is involved. It’s recommended to define Document Router’s Input directory as the Webservices working directory. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for create-Requests). Please note: In case of synchronous requests, the correct mime type will be determined automatically by the webservice. In case of asynchronous requests the mime type will be appended at the end of the file generated at the asynchronous directory location. Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 getAll Document[] ContentServerDocGetAll(String ApplicationName, Document document, String UserName, String seckey, Boolean FetchContent) This API may be used in order to feth the specified documents. In case no component was provided, all components will be feteched. Each component will be returend as a separate document structure. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID: The document ID which was given to the document when it has been archived. (Optional) CompID: The component ID which should be retrieved from the document. In case no component Id was provided, data will be used as component Id. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for create-Requests). FetchContent: Defines whether the content should be delivered or not. Returns a document structure containing the following: An array of bytes containing the component The size of the component The document type mapped against a mime type. The HTTP Return code. Return code: 200: OK 400: Bad request Check if application is active Check if specified application name is correct on both sides Check if username is delivered by remote end 401: Forbidden Check if seckey is valid Check if instance is allowed to do serverinfo-requests Check if the correct certificate is being used which is mapped against an alias and the common name (CN) contains the application name. 500: Internal Server Error Check logs for additional details 1 MDocument[] ContentServerDocGetAllv2(String ApplicationName, MDocument document, String username, String secKey, Boolean fetchContent, boolean convertToPDF, Boolean ConvertToMul-tiPagePDF, String watermark) This API may be used in order to feth the specified documents. In case no component was provided, all components will be feteched. Each component will be returend as a separate document structure. ApplicationName: Application which is mapped against a specific Content Server. document: A document structure needs to be provided with the following fields filled. DocID: The document ID which was given to the document when it has been archived. (Optional) CompID: The component ID which should be retrieved from the document. In case no component Id was provided, data will be used as component Id. UserName: Username which is delivered / provided by the client (Authentication should be handled at the remote end. Webservice itself doesn’t offer user authentication.) (Optional) seckey: The seckey represents a signed ApplicationName. In case the security is enabled and the alias is specified, the seckey will be verified against the configured alias in the keystore. (Seckey is optional for create-Requests). FetchContent: Defines whether the content should be delivered or not. ConvertToMultiPagePDF: Specifies whether a component should be converted to a Pdf file. In case this flag is being activated components of the following type will be converted to PDF and merged as a single Pdf file: JPEG JPG TIF TIFF Watermark: Defines whether a Pdf should be marked with the specified watermark text. 2public class Document {
//This represents the document ID
String docID;
//This represents the extension of the component
String docType;
//This represents the actual “data” which should be converted to a readable data by the //de-veloper
byte[] data;
//This represents the Component ID
String compId;
//This represents the size of the component
String compSize;
//This represents the response code of the server request
String status;
}
Automation of configuration
You may automate the following configuration: License Key Configuration List of instances In order to automate the pre-configuration please follow these steps. The following directory should be place at the root level of the web application resource (e.g.: inside the KGSAdmin-WebService.war-file) KGSAdmin-WebService.war\conf\webservice\ WebService.<Name of the Webservice-instance>.cfg WebService MainConfiguration.cfg The name of the file itself indicates the name of the webservice instance, which will be configured automatically. The file has to follow this schema. This configuration will configure a webservice instance with the name Test for a Content Server URL running on the same webserver (localhost), the content repostiroy FI and the working directory /tmp/webservice-directories/test . The working directory will be used for asyncronous requests where relevant index files for the Document Router will be created. Please check the API int ContentServerDocCreate(String Application-Name,String docid,String CompID, Document doc, boolean async) for additional details regarding asynchronous requests. In addition to instances you may also automate pre-configure the webservice license key. The following schema defines the contents of the WebService MainConfiguration.cfg-file<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>ReadConfig=1</comment>
<entry key="Common.ContentServer URL">http://localhost:8080/KGSAdmin-CS/contentserver</entry>
<entry key="Common.Repository">FI</entry>
<entry key="Common.Working Directory">/tmp/webservice-directories/test</entry>
</properties>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>KGS Admin Bundle Configuration</comment>
<entry key="Main.License Key">YOUR-LICENSE-KEY</entry>
</properties>
Security
Security may be turned on or off per web service instance. In order to activate the security, please follow this guide. Please oben the web user interface of tia Webservice and click on the gear symbol in the actions column of the webservice instance you wish to activate security for. This will open the configuration of the instance. tia Web Service UI with highlighted gear-symbol in the Action column. Please switch to the tab Security and tick the checkbox of the option UseSecurity. Three types of security are being supported. Checking, if the application’s name is signed Sending read-/write-operations using configured certificate Permission regarding content server operations (serverinfo, info, create, delete and get) Three fields should be configured in order to verify that the application name is signed. PublicKeystore Path (May be found here OSGi → Configuration → WebService MainConfiguration PublicKeystore Password (May be found here *OSGi → Configuration → WebService MainConfiguration) PublicStoreAlias (Main → tia Web Service → Instance name → Gear-symbol → Security-tab → PublicStoreAlias You may configure a keystore which consists of one or many certificates (with public keys). When a seckey is received by an instance, seckey’s signature will be verified against the alias configured at the web service’s instance configuration. After enabling the UseSecurity setting and configuring a keystore alias, the signing of the application’s name will be verified using the public key mapped against the alias in the specified keystore. Please note: It’s necessary to restart the instance in order for the security settings to take effect. The option Certificate within the Security-tab ( Main → tia Web Service → Gear-symbol in the Actions column of the instance) allows you to use different types of certificates. Currently you may choose from the following types. KGS ID3 none Please note: In case the remote content server does not contain any certificate, you may send a certificate from a specific web service instance, by clicking the key-symbol. tia Web Service UI with highlighted “Send certificate”-action. It’s also possible to send certificates to every web service instance with configured security, by clicking the Send Certificates-button at the bottom of the instance overview. An web service instance may be configured to allow certain or all operations. The following operations are possible. serverinfo: The web service instance allows to execute serverinfo-requests against the defined content server endpoint. info: The web service instance allows to execute info-requests against the defined content server endpoint. create: The web service instance allows to execute create-requests for documents against the content server endpoint. delete: The web service instance allows to execute delete-requests for documents against the defined endpoint get: The web service instance allows to exeute get-requests for documents against the defined endpoint Please note: These options and permissions work separated from the UseSecurity-option. Therefore the parameter UseSecurity does not has to be enabled. You may find these options by opening the web userinterface → Main → tia Web Service → Gear-symbol in Actions-column of the instance → Security-tab Opened web userinterface with highlighted request permission options In order to import a certificate with public key, which will be used for verfication, please follow this guide. Open the web userinterface of the Web Service and go to Main → tia Web Service. Please make sure, that the Public Keystore Path, the PublicKeystore Password as well as the PublicStoreAlias have been configured. Next to the Web Service instance please click on the Import-icon, which will open a dialog. In this dialog you’ll have enter the alias and locate the certificate by clicking the browse button. After both have been set, please click on the Import-button. In case an alias already exist or the certificate is not valid with a public key, an error will be generated. Opened instance overview of Web Service with highlighted “Import”-button and opened “Import Public Key”-modal This allows an instance to generate a certificate send request (CSR) at a specified folder to be signed by the authorized authority (e.g. CA). In order to use this feature please make sure that the following parameters have been configured in the instance. The PrivateKeystore Path The PrivateKeystore Password The OutputCSRDirecotry Path The PrivateStoreAlias This will generate a CSR file using the name of an Instance. For example, if the instance name is “Cortex”, the CSR file will be “Cortex.csr”. It is expected that the CSR file will be signed by the ap-propriate authority and later a CER file will be sent back. Once the CER file has been received, please import the CER into the public Keystore by following the steps mentioned in 6.4. Usually an instance may use a certificate in case the common name (CN) consists of the application name itself. For example, if the application “Cortex” is to use a certificate which has the common name “test.kgs-software.net”, the request will not succeed. However, if the parameter “CNOverride” is configured to use “test”. In this case, the request will succeed as the application “Cortex” is allowed to use the certificate with the common name, “test”. The PublicStoreAlias should also be configured with the correct alias. We have developed a command-line tool to generated signed Text based on the input given by the user which is usually the application Name. However, there is also a possibility of generating the signed text from the GUI of the Framework. The option is located at “Main -> KGS Web Service -> Generate SecKeys” as shown below. Web userinterface with highlighted “Generate SecKeys”-button. After you click this option, a CSV file will be generated consisting of the application/instance names along with the signed texts (security keys). In order to use this option, following are the prerequisites. The path to the directory should be configured where the CSV file will be generated. The path to a valid Private Keystore along with valid Password have to be configured The PrivateStoreAlias for the respective application name should be configured 
Signing an application’s name
Using a certificate
Configuring permission for Content Server operations
Importing a certificate with Public Key
Generating a Certificate Send Reuest (CSR)
CSR attributes must be confirgured before the request can be generated. Important attributes are located at Main -> KGS WebService -> Instance name properties -> Security.Overriding Common Name
Generating Signed Keys
Found at OSGi → Configuration -> WebService MainConfiguration -> SecurityKey Path
Found at Main -> KGS Web Service -> click on configure for the respective application (instance) -> Security -> PrivateStoreAlias
Testing
Scheduler
The scheduler checks after configured intervals the validity of the certificates contained within the configured public Keystore. The scheduler Configuration can be accessed via OSGi -> Configuration -> Scheduler MainConfiguration. Parameter Found at Description Default value / Examples CertDayValidity OSGi → Configuration → Scheduler MainConfiguration Checks whether the cer-tificate will be valid after configured days Default: 0 CertHourCheck OSGi → Configuration → Scheduler MainConfiguration Scheduler will check the validity of the certificate after configured hours. Default: 0 CheckWebService OSGi → Configuration → Scheduler MainConfiguration Indicates whether the public keystore configured. Default: False Debug OSGi → Configuration → Scheduler MainConfiguration Level of Debug info Default: 0 0 - No Debug, only Error messages and “alive” message As of now, the Scheduler ONLY checks the public Keystore belonging to the WebService bundle. Parameter Found at Description Default value / Examples CertDayValidity OSGi → Configuration → Scheduler MainConfiguration Checks whether the cer-tificate will be valid after configured days Default: 0 CertHourCheck OSGi → Configuration → Scheduler MainConfiguration Scheduler will check the validity of the certificate after configured hours. Default: 0 CheckWebService OSGi → Configuration → Scheduler MainConfiguration Indicates whether the public keystore configured. Default: False Debug OSGi → Configuration → Scheduler MainConfiguration Level of Debug info Default: 0 0 - No Debug, only Error messages and “alive” message As of now, the Scheduler ONLY checks the public Keystore belonging to the WebService bundle.
Example: 5
Scheduler will check whether the certificate(s) will be valid after 5 days.
Example: 24
the scheduler will check the certificates after every 24 hours.
Example: true indicating webservices’ configured public keystore should be checked
1 - Error Logs will be logged
2 - Warning logs will be logged
3 - Info logs will be logged
4 - Debug logs will be logged
Example: 5
Scheduler will check whether the certificate(s) will be valid after 5 days.
Example: 24
the scheduler will check the certificates after every 24 hours.
Example: true indicating webservices’ configured public keystore should be checked
1 - Error Logs will be logged
2 - Warning logs will be logged
3 - Info logs will be logged
4 - Debug logs will be logged
Historical Documents
The Webservice contains the proxy logic for re-routing “read” and “get” requests to a historical repository or to a historical content server. Below are few Sample Configurations. Scenario A: The historical and new repositories are located on the same Content Server, but have different content repository Ids. Configuration for scenario A Scenario B: The historical and new repositories are located on different Content Servers, but have the same content repository Id. Configuration for scenario B Scenario C: The historical and new repositories are located on different Content Servers and have different content repository Ids. Configuration for scenario B
Document Type mapping
The following document types are mapped with the corresponding MIME-types. Name Mime Type 323 text/h323 3g2 video/3gpp2 3gp video/3gpp 7z application/x-7z-compressed AA audio/audible AAC audio/aac ALF application/x-alf BIN application/octet-stream BMP image/bmp CSV text/csv DOC application/msword DOCX application/vnd.openxmlformats-officedocument.word-processingml.document DWF drawing/x-dwf FAX image/tiff GIF image/gif GTAR application/x-gtar GZ application/x-gzip HTM text/html HTML text/html JPG image/jpeg M4A audio/m4a M4B audio/m4b M4P audio/m4p M4R audio/x-m4r M4V audio/x-m4v MOVIE video/x-sgi-movie MP3 audio/mpeg MP4 video/mp4 MP4V video/mp4 MPG video/mpeg MPP application/vnd.ms-project MSG application/vnd.ms-outlook OTF application/x-otf PCX image/pcx PDF application/pdf PNG image/png PPT application/vnd.ms-powerpoint PS application/postscript RAW application/x-raw REO application/octet-stream RTF application/rtf SCR application/x-scr TAR application/x-tar TIF image/tiff TIFF image/tiff TXT text/plain VSD application/vnd.visio WAV audio/wav XLS application/vnd.ms-excel XML application/xml Z application/x-compress ZIP application/x-zip-compressed In case no suitable mime type is found in our internal table (as shown above), Java will try to detect the appropriate mime-type. If no suitable mime-type is found even by Java, then an error will be re-turned. It is also possible to override the mime types or introduce new/customized mime types with the parameter “MimeType Path” available at “OSGi” -> “WebService MainConfiguration”. This op-tion allows us to specify a file which contains a table. This table can be used to override the mime type. The installation contains a sample file (\mimeType) which would allow us to override the mime types. Example; application/pdf pdf application/ocsp-response ocsp If the text file is updated, please restart the instance(s) in order to take effect. To configure a specific instance to read from the mimeType table, simply activate the flag “Override Mime-Types” located at “Main -> KGS Web Service -> Application Manager “. Edit the Instance configuration and under “Common”, the flag is located. Simply check the box to configure the in-stance to read from the mime type table as shown below. Highlighted Mime type override option
C:\mimetype\mime.types
Following line specifies that the “pdf” will be mapped to “application/pdf”.
Following line specifies that both “bin” and “dms” will be mapped to “application/octet-stream”;
application/octet-stream bin dms
Following line will be ignored (‘#’ would allow the mime type reader to ignore the line);