...
...
...
...
...
...
...
...
...
...
...
...
Ressources
are linked within the containing article!
Remarks
| Excerpt |
|---|
covering the higher-level client API of the Web-API Gateway, as it is useful for client application developers. |
...
| border | true |
|---|
| Column | ||||
|---|---|---|---|---|
Table of Contents
|
There currently are two documented client services:
- web api gateway - offering a labels layer in order to allow for multi-language applications, offering standard forms used to display object metadata in an appropriate manner - and offering functionality to cope with user settings and associated issues
- viewer service - offering views for a couple of common file types to be displayed directly in a client application. It is designed allow for easy integration of further viewers in addition to the free ones included already.
The third client service, the user service, is accessed through the web api gateway.
Introduction
The yuuvis core service is considered as a backend for storing billions of objects and being strong in performance as well. To keep this performance all functionalities for a client that offers standard document management functionalities should be served by additional services. The Web-API Gateway Service is beside the User Service and the Viewer Service the main service for the client.
First of all, the service allows configuring the labels of object types and field names that should be shown to the users depending on the language the user has set in the client.
The second feature is to deliver standard forms for each object type and for the situations CREATE and EDIT, and maybe for SEARCH if necessary later on.
There is a Swagger-UI for WEB-API Gateway where the administrator is supported by interfaces to maintain the data manually.
Programmers are getting here the URLs for the endpoints of a PUT or GET call: https://<host>/api-web/swagger-ui.html
Maintenance of localized labels
The Web-API Gateway offers several endpoints for storing JSON-formatted files that list all labels for the tenant-specific schema as well for the system schema, and for reading all labels for a specific language.
The JSON-format for labels
The following example is a file that lists all system-specific labels for object types and standard attributes. Each technical name begins with a prefix followed colon and the object type name or the field name. The extensions '_label' and '_description' uses the client to display key value.
In the case of object types, the '_description' is used to group them (aka object type group in yuuvis RAD), currently in the smart search control.
In the case of field names, the '_description' is shown below the form field.
| Code Block | ||
|---|---|---|
| ||
{
"system:folder_label": "Root folder",
"system:folder_description" : "01 Across over",
"system:document_label": "Root document",
"system:document_description": "01 Across over",
"system:baseTypeId_label": "Basistype ID",
"system:objectTypeId_label": "Type",
"system:secondaryObjectTypeIds_label": "Secundary types",
"system:parentObjectTypeId_label": "Context type",
"system:objectId_label": "Object ID",
"system:parentId_label": "Context ID",
"system:createdBy_label": "Creator",
"system:creationDate_label": "Created",
"system:lastModifiedBy_label": "Editor",
"system:lastModificationDate_label": "Edited",
"system:versionNumber_label": "Version",
"system:tenant_label": "Tenant",
"system:traceId_label": "Trace ID",
"system:contentStreamLength_label": "File size",
"system:contentStreamMimeType_label": "Mimetype",
"system:contentStreamFileName_label": "Filename",
"system:contentStreamId_label": "Content ID",
"system:contentStreamRange_label": "Content range",
"system:contentStreamRepositoryId_label": "Content Stream Repository",
"system:digest_label": "Digest",
"system:archivePath_label": "Archive path",
"system:rmExpirationDate_label": "Retention date",
"system:rmStartOfRetention_label": "Retention start",
"system:rmDestructionDate_label": "Destruction date",
"system:rmDestructionRetention_label": "Retention",
"system:parentVersionNumber_label": "Context version",
"appClient:minidoc_label": "Smallest Document",
"appClient:minidoc_description": "01 Across over",
"appClient:clienttitle_label": "Title",
"appClient:clientdescription_label": "Description",
"appClient:titledescription_label": "Title & Description"
} |
Hint: The key-value pairs "appClient:clienttitle_label" and "appClient:clientdescription_label" are used in the header of the object details and as rows in all result lists. The technical names are configured in the appClient-Schema (see below). The secondary object type 'clientdefaults' must be referenced in each object type that should be handled in the client.
Convention: In the case of object types the _description is currently used for a grouping in the object type selection dialog that is offered for the smart search control as well as in the create object state. This way of configuring a grouping will be replaced by another configuration. We recommend to use digits in front of the object type group as can be seen here:
This is the schema for appClient with the definition of clienttitle and clientdescription:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/">
<propertyStringDefinition>
<id>clienttitle</id>
<propertyType>string</propertyType>
<cardinality>single</cardinality>
<required>true</required>
<maxLength>200</maxLength>
</propertyStringDefinition>
<propertyStringDefinition>
<id>clientdescription</id>
<propertyType>string</propertyType>
<cardinality>single</cardinality>
<required>true</required>
<maxLength>200</maxLength>
</propertyStringDefinition>
<typeDocumentDefinition>
<id>minidoc</id>
<baseId>system:document</baseId>
<contentStreamAllowed>required</contentStreamAllowed>
<secondaryObjectTypeId>clientdefaults</secondaryObjectTypeId>
</typeDocumentDefinition>
<typeSecondaryDefinition>
<id>clientdefaults</id>
<description>contains title and description fields mainly for mixed resultlist and object header</description>
<baseId>system:secondary</baseId>
<propertyReference>clienttitle</propertyReference>
<propertyReference>clientdescription</propertyReference>
</typeSecondaryDefinition>
</schema> |
Save tenant-specific labels
Open the admin-controller and then the click onto the URL ../admin/resources/text/{locale} to open the maintenance form.
Copy the JSON-formatted data into the input field resource and type the DIN value for the corresponding language, e.g. de for Deutsch, and en for English.
Save the data with a click onto 'Try it out'. Observe whether the data could be saved as described in the response message area.
Save system-specific labels
Open the system-controller and then the click onto the URL ../system/resources/text/{locale} to open the maintenance form.
Copy the JSON-formatted data into the input field resource and type the DIN value for the corresponding language, e.g. de for Deutsch, and en for English.
Save the data with a click onto 'Try it out'. Observe whether the data could be saved as described in the response message area.
Read all labels
Open the resource-controller and then the click onto the URL ../resources/text, to open the maintenance form.
Type the DIN value for the corresponding language, e.g. de for Deutsch, and en for English.
Click onto 'Try it out' and see all key-value pairs for labels and descriptions in Response Body.
Maintenance of forms
Beginning with version Summer 2020 (aka 2.2) it is possible to store custom form in JSON-format.
The following code shows a form example:
| Code Block |
|---|
{
"name": "appPersonalfile:pfpersonalfile",
"situation": "EDIT",
"script": "scope.model['appPersonalfile:pfname'].onchange=writetitle; scope.model['appPersonalfile:pffirstname'].onchange=writetitle; scope.model['appPersonalfile:pfclass'].onchange=writedescription; function writetitle(){scope.model['appClient:clienttitle'].value = scope.model['appPersonalfile:pfname'].value + ', ' + scope.model['appPersonalfile:pffirstname'].value;}; function writedescription(){scope.model['appClient:clientdescription'].value = scope.model['appPersonalfile:pfclass'].value}",
"layout": {
"align": "column"
},
"elements": [
{
"type": "o2mGroup",
"name": "core",
"layout": {
"align": "row"
},
"elements": [
{
"type": "o2mGroupStack",
"layout": {
"align": "row"
},
"elements": [
{
"type": "o2mGroup",
"name": "appPersonalfile:data",
"layout": {
"align": "column"
},
"elements": [
{
"name": "appPersonalfile:pfname",
},
{
"name": "appPersonalfile:pffirstname",
},
{
"name": "appPersonalfile:pfclass",
},
{
"name": "appPersonalfile:pfentrydate",
}
]
},
{
"type": "o2mGroup",
"name": "appClient:titledescription",
"layout": {
"align": "column"
},
"elements": [
{
"readonly": true,
"name": "appClient:clienttitle",
},
{
"readonly": true,
"name": "appClient:clientdescription",
}
]
}
]
}
]
}
]
} |
This is the result the user can observe in the client. The names (see in the code above) are exchanged by the Web-API Gateway with respect to the language the user has set for the client.
In the future, a designer will allow modeling the forms in a graphical manner.
Save tenant-specific forms
Open the admin-controller and then the click onto the URL ../admin/form/{type}?situation={situation} to open the maintenance form.
Copy the JSON-formatted data into the input field 'form', write the object type name (e.g. tenKolibri:personalfile) into field type, and type CREATE or EDIT into the field situation.
Save the data with a click onto 'Try it out'. Observe whether the data could be saved as described in the response message area.
The form will be vaildated.
Get tenant-specific forms
Open the admin-controller and then the click onto the URL ../admin/form/{type}?situation={situation} to open the maintenance form.
Copy the JSON-formatted data into the input field 'form', write the object type name (e.g. tenKolibri:personalfile) into field type, and type CREATE or EDIT into the field situation.
Get the raw data without enriched properties with a click onto 'Try it out'.
Save system- and app-specific forms
Open the system-controller and then the click onto the URL ../system/form/{type}?situation={situation} to open the maintenance form.
Copy the JSON-formatted data into the input field 'form', write the object type name (e.g. appPersonalfile:personalfile) into field type, and type CREATE or EDIT into the field situation.
Save the data with a click onto 'Try it out'. Observe whether the data could be saved as described in the response message area.
The form will be vaildated.
Get system-and app-specific forms
Open the admin-controller and then the click onto the URL ../system/form/{type}?situation={situation} to open the maintenance form.
Copy the JSON-formatted data into the input field 'form', write the object type name (e.g. appPersonalfile:personalfile) into field type, and type CREATE or EDIT into the field situation.
Get the raw data without enriched properties with a click onto 'Try it out'.
Read forms
Open the dms-controller and then the click onto the URL ../dms/form/{type}?situation={situation}, to open the maintenance form.
Type the DIN value for the corresponding acceptance-language, e.g. de for Deutsch, and en for English, write the object type name (e.g. appPersonalfile:personalfile) into field type, and type CREATE or EDIT into the field situation.
Click onto 'Try it out' and see all key-value pairs for labels and descriptions in Response Body.
Introduction
Main part(s)
Subsection(s)
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
for (int i = 0; i < 10; i++)
{
System.out.println("Hello World " + i);
} |
...
| Page Properties | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ressourceshttps://wiki.optimal-systems.de/display/devkolibri/yuuvis+Momentum+-+Flex+Viewer+Service RemarksThere is description for extending the viewer service mentioned to be existing in git (ask Jürgen) - however, the link is missing. Get that documentation and cast it into a tutorial article linked to this viewer service concept article! The link pointing to the "freely available" viewer components, also meant to be in git, is also inoperable or not accessible to anyone outside of team kolibri... → grab and integrate that info. Supported filetypes look nicer when in tables:
The API description lacks information... These sentences are somewhat confusing and should be checked with the PO:
Additionally provided parameters will be passed to the custom viewer. (I believe this should read: any further parameters provided will be passed to the custom viewer) Place links for further reading at the bottom (api-gateway, functional extension - client side, architecture, a still-to-be-written customization tutorial) |
| Excerpt |
|---|
Supported filetypes and how to extend the viewer services capabilities |
| Section | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
Introduction
The yuuvis® Momentum viewer service offers to display several common filetypes directly within a yuuvis® Momentum client application. It serves within the yuuvis® Momentum reference client and can readily be integrated in a custom client. It is designed allow for easy integration of further viewers in addition to the free ones included already.
This article is intended for administrators who want to know about the supported file types so they can decide whether to let the viewer service be extended for not supported ones.
the viewer service API
For the viewer to process the request a path pointing to the file to be displayed must be accessible. The mimeType or size may be omitted here, if provided in the Request Header.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
URL/?path={pathToTheFile}&mimeType={mimeType}&size={fileSize} |
- path: the direct path from where the file can be loaded (required)
- mimeType: the files mimeType (if not provided, the service tries to get it from request headers. If also not available there, an error page is shown)
- fileSize: the size of the file (if not provided, the service tries to get it from request headers. If also not available there, an error page is shown)
Custom viewer configuration
The viewer service can be extended by adding a few lines to its configuration.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
[
{
"mimeType": "text/x-web-markdown",
"fileExtension": ["md"]
"viewer": "{pathtoapplicationindex.html}?path=${path}#locale=${locale}&direction=${direction}&theme=${theme}&accentColor=${accentColor}"
}
] |
- mimeType may also be a string Array, containing multiple mime types
- file extension is not mandatory. Provide only if mimeType is not unambiguously.
Additionaly, non mandatory parameters are provided (corresponding to the client settings)
- darkMode: boolean = sets class darnk to the body (default = false).
- direction: string = sets the document direction to the body (default = „LTR“).
- accentColor: string = set the accent color as css varibale to the html tag (default = „“).
- local: string = sets the document locale to the html tag (default = „en-US“).
- fileExtension: string = if mimeType is not unambiguously, provides a more clear file specification.
Additionally provided parameters will be passed to the custom viewer.
Supported Types
For unsupported filetypes, the viewer service sents a notification and a download link, allowing for the content to be downloaded and viewed by an external application.
Audio
Used component: By default audio files are natively played by the Browser with HTML5 Audio. (that is a subject of the HTML5 Audio specification).
Default component: Used component.
Mimetype: mpeg, mp3, ogg, wav
All played files are streamed to prevent unnecessary data downloads. The autoplay is set to false.
Image
Used component: Custom Angular Application with angular-x-image-viewer plugin.
Default component: By default, the supported mimeTypes are rendered in the standard HTML img tag.
Mimetypes: jpeg, gif, png, svg, bmp, png, ico
Not supported file types are by default offered as a download.
JSON
Used component: Custom Angular Application with ngx-json-viewer plugin.
Default component: Used component.
Mimetype: application/json
Mails
Used component: eml files are parsed by mailparser.
Default component: Used component.
Mimetypes : message/rfc822 (eml)
Not supported file types are by default offered as a download.
Markdown (text/markdown)
Used component: Custom React Application with markdown-to-jsx plugin. / Custom Angular Application with showdown plugin.,
Default component: Used component.
Mimetypes: x-web-markdown, markdown
Open Document Format
The ODFs are currently resolved as application/zip. The viewer analyses all such mime-types additionally and reacts in this case on the file extension that must be provided.
Used component: Files are parsed and rendered with https://webodf.org/
Default component: Used component.
File extension: odt, ods, odp
Mimetypes: application/zip (as resolved by yuuvis core service)
Text (text/plain)
Used component: By default plain text is natively rendered by the Browser.
Default component: Used component.
Mimetypes: plain
XML(text/xml)
Used component: By default xml is natively rendered as text by the Browser.
Default component: Used component.
Mimetypes: xml
Used component: PDF.js which is a Mozilla project.
Default component: Used component.
Mimetypes: application/pdf
The ranging support by PDF.js is supported by yuuvis API as well.
Video
Used component: By default video files are natively played by the Browser with HTML5 Video (that is a subject of the HTML5 Video specification).
Default component: Used component.
Mimetypes: mpeg, mp4, ogg, webm
All played files are streamed to prevent unnecessary data downloads. The autoplay is set to false.
Summary
You where provided with an overview of the filetypes supported by the viewer service and its concept of extensionability.
| Info | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||
Read on
|