Connector for dg hyparchive in applications

Applications module Integrate external data

1. Application development

1.1. Data groups

To be able to save stamp data and documents in hyparchive via Intrexx, a standard Intrexx data group is required. External data groups are currently not supported by the Connector. The data group's fields can then be connected to hyparchive stamp fields. A file field, which contains a special FileHandler class for hyparchive, is added to the data group for files.

It is fundamentally possible to create multiple hyparchive data fields, it is however recommended to use one per data group as the assignment of the stamp fields will otherwise become unclear.



Select the data group, which should be connected to hyparchive, in the application structure and create at least the following data fields via the New menu / Data field:

1.2. File fields




Afterwards, create another field with the "File" data type. Click on "more...".



Select the option "Intrexx handlers" and then "dg hyparchive Handler" from the drop-down list. Confirm your selection with "OK".



Open the properties dialog of the new file data field by double-clicking on it in the application structure. You can view the data fields in the application structure by selecting Edit / Show data fields when the data group is selected. The title of the field and the handler class selected in the previous step are shown on the General tab. The following specifications are also required:

1.3. Stamp fields

1.3.1. Assignment of Intrexx fields

Switch to the Data field mapping tab. The Intrexx data fields / values are assigned to the dg hyparchive stamp fields here.



Hyparchive stamps from the previously selected hyparchive server will be listed on the left-hand side. On the right-hand side the Intrexx data groups, and when appropriate the fields of parent group and user defined values, are listed. Hyparchive fields can be filtered by stamp to enable a better overview. The arrow key allows you to assign hyparchive fields and Intrexx data fields. When a data set is saved in Intrexx, then the value of the Intrexx data field is automatically saved in the linked hyparchive field. An important consideration is that the data type in hyparchive must be compatible with that of the Intrexx data field.

1.3.2. Assignment of user-defined values

As well as data fields, user-defined values can also be assigned to hyparchive fields. To do this, click on Add value.



Select from the following options: Static value, System value, GUID or Null value. This is for example helpful, if the same value should always be used for a mandatory stamp field. In the same way calculated date values and system values, like the current Intrexx user for example, can be recorded. Another example would be the generation of a GUID at the current time as a clear data set ID for Intrexx and hyparchive. Click here for help with this dialog. Calculated values are as standard not saved in Intrexx data fields, but rather in hyparchive fields. For certain purposes it is necessary to save a static value in an Intrexx data field. As a result, you will be asked automatically if the value should be saved in an Intrexx data field, when assigning a value to a hyparchive field.



The setting Save value in data field can be activated here. Click on "OK".



The setting "Save value in data field" can be edited in the Field assignment tab by clicking on Save value in data field.

1.3.3. Assignment of drop-down lists

Just like Intrexx, hyparchive offers the possibility to define drop-down lists for data fields. Fields that have drop-down lists have the file type "sngsel" or "mltsel" (for lists with multiple choices) in hyparchive. Drop-down lists in hyparchive can be assigned values from Intrexx data fields or static values. Please note that the corresponding drop-down list entry in hyparchive can be ascertained from the value in Intrexx. If an Intrexx data field with the type string is assigned to the list field, then the value, which is saved there, must correspond with a display value in the hyparchive drop-down list. And please note that this is case sensitive.

1.3.4. View and edit pages

The usual data field controls on view and entry pages are available to view and edit the stamp fields. So that Intrexx can identify the document, which is linked to each data set, in hyparchive, it is necessary to place the fields for Department ID and Document ID on every view and edit page that is related to hyparchive. The Department ID can be determined in the properties of the file field on the Settings page of the Expert tab (value of the key "hyparchive.department.id").



To display dg hyparchive documents in the Intrexx application, the corresponding data records with the correct Department ID and Document ID need to be created. This can also be done in the hidden area, so that the fields are not visible to the users. If the stamp data of a document is directly edited in hyparchive, then it cannot be automatically and immediately synchronized in Intrexx. Therefore Intrexx updates the fields of a hyparchive stamp automatically, as soon as the data set is opened on a view or entry page. The user needs to click on "Save" to save the updated data in Intrexx.

1.4. Authentication

The final step of configuring the file field can be defined on the tab Authentication tab. Here you can decide which portal user should be used for the authentication when accessing hyparchive.



By default the currently logged in portal user will be used. If there is not any hyparchive session for this user and the option "Username/Password" was selected as the authentication method in the configuration, then the portal user will be requested to log in to hyparchive. There are application cases, where access to hyparchive should always be made with one user, irrespective of which portal user is currently logged in. This is for example the case if there is not a hyparchive user for every portal user or if documents from Intrexx should fundamentally be saved under the same user name in hyparchive. To do that a so-called static user can be selected in the dialog. This refers to an Intrexx user, who has been assigned to a hyparchive user in the hyparchive configuration. A static user can also be directly setup with this dialog. As soon as such a user is entered in the file field, then all access to hyparchive takes place with the data group of this hyparchive user account. This means that an interactive login to hyparchive is no longer necessary in the portal. This also makes simple Single Sign-On scenarios possible without having to revert to the Kerberos authentication.

1.5. dg hyparchive data group handler

As soon as a data field for hyparchive is added to an Intrexx data group and then configured, then the data handler class will automatically be adjusted in the expert attributes of the data group at: 
de.uplanet.lucy.server.dghyparchive.connector.rtdata.RtDataGroupTableHypArchive
This can also be carried out at a later point in time.

The hyparchive specific data group handler class is optional, but offers additional functionality in interaction between Intrexx and hyparchive. In this way an automatic synchronization of the stamp values from hyparchive is carried out as soon as a hyparchive data set is loaded on an Intrexx view or entry page. In doing so it is guaranteed that an Intrexx portal user can constantly see the current stamp data. In some circumstances it can also occur that stamp data was edited in hyparchive but the previous value is still saved in Intrexx.

1.6. Regional settings

Date/time and currency fields are formatted by hyparchive with the format that was setup by the user under Regional settings. hyparchive requires the entire language/culture code (e.g. "de-DE" or "en-US" instead of "de" or "en">). The formats of the required languages can be defined in the Portal properties. Alternatively you can determine a standard language for hyparchive in the configuration of the file field. In this case, the same language code will be used every time a file is recalled. Please note that you need to setup the format in Intrexx that hyparchive expects for the date/time and currency fields.

1.7. Support of SAP documents

To support SAP ArchiveLink documents (available in Intrexx 8 with Online Update 07 or later), the following additional settings need to be made in the application:
  1. A data field with the type Short text is required for the SAP Archive ID.
  2. In the properties dialog of the file field, the following settings must be added on the Expert / Settings tab:
    • hyparchive.sap.archive = true (Type: Boolean)
    • hyparchive.sap.archive.id.field.guid = [GUID of the SAP ArchiveLink ID data field] (Type: GUID)

1.8. Expert settings

In the properties of the file field, it is possible to further configure the connector by going to the Expert tab. The following settings are available here:

2. dg hyparchive in Portal applications

2.1. Authentication

When accessing a data group, which contains hyparchive file data fields, with a portal application for the first time, the user will be requested to login to hyparchive. This is only required once per session and hyparchive server. If Windows Integrated Authentication is activated then the user will automatically be logged in upon accessing hyparchive for the first time. A login is not required if a static user was defined in the file field of the data group for hyparchive authentication. The hyparchive data can then be accessed via the Intrexx application after successful authentication. The portal user has the same functions available to him with hyparchive data groups, as he does with the normal Intrexx data groups. In terms of the file operations there are however less special features to consider.

2.2. File operations in view tables

hyparchive file data fields can be placed in view tables to open files directly from tables. However, for performance reasons no files from hyparchive are by default displayed in file data fields, when they are displayed in a view table. To do that, activate the option "Show files from the dg hyparchive in view tables additionally" in the file data field configuration. If it should be possible to directly download documents from the table, then this needs to be activated in the options of the file data field in the view table.
Please note that thumbnails for hyparchive files cannot be displayed, because these are not stored on the Intrexx Portal Server but in hyparchive. Therefore preview pictures also cannot be generated by Intrexx.

2.3. File operations on view pages

hyparchive files are displayed on view pages with the control View file selection.



It is also possible to enable the downloading of files here.

2.4. File operations on edit pages

The File selection control on edit pages allows you to upload and edit files and documents in Intrexx and then save them in hyparchive. All of the functions from the default Intrexx file data fields are available here



In addition to allowing downloads you can also determine what should happen when files are uploaded. In principle, new files will be added to the existing files in hyparchive document folders. It is however possible to replace the files.



Additionally you can determine the maximum number of files per data set that can be saved. The maximum file size can also be specified here. There are also advanced functionalities for uploading files, which have an effect on the behavior of the control in the portal. Files can be moved onto the file control via drag & drop in the browser and with that they will be automatically uploaded to the Intrexx Server. When the entry page is saved, then the file as well as the information in the stamp fields will be transferred to the hyparchive server. The new Document ID will be saved in Intrexx. Existing files can be deleted in hyparchive by clicking on "Delete".

In terms of single file documents, files can be updated (in this case replaced), by first deleting the existing file and then uploading a new file.

2.5. File operations in drop-down lists

To make it as easy as possible for the portal users to be able to maintain hyparchive stamp fields, they can add identical drop-down lists on entry pages in Intrexx for the drop-down lists in hyparchive. The values from hyparchive drop-down lists can be identified with the hyparchive FormEdit Tool. On an entry page in Intrexx a drop-down list can be created, its entries reflect those of a hyparchive value list. The values can be defined from applications, references or user defined value.

2.6. Updating stamp data

Seeing as documents and files are only saved and available in hyparchive, they are constantly up-to-date, when they are accessed with Intrexx. The stamp data of a document behaves somewhat differently. This is saved in both the data fields of the Intrexx data group as well as in hyparchive. This has the advantage that you can search by stamp fields and access the data sets in Intrexx without having to access hyparchive server. The disadvantage of this method is that the metadata of a document in hyparchive can change over time, whilst the old values are saved in Intrexx.

As Intrexx cannot automatically be informed by hyparchive about changes to stamp fields, the stamp data in Intrexx is updated as soon as a data set on a view or entry page, which contains a hyparchive data field, is loaded. When the page is saved, the updated data will be resaved in Intrexx.

Another method for keeping stamp data constantly in sync between Intrexx and hyparchive is made possible by using processes.

2.7. Possible search options

2.7.1. Possible search options

Documents and files in hyparchive data fields are only stored on the hyparchive server. Therefore it is not possible for the Intrexx search engine to index the contents of the files, in order to make them available for search requests. Single data stamps, which are saved in Intrexx data groups, can be searched through with the Intrexx search function. The hyparchive web service interface offers the option to search for documents in hyparchive with hyparchive full-text search. The results must then be processed in a suitable way for Intrexx. Therefore clicking on a hit will open the document in the hyparchive Web Client or will open the corresponding data set, which has the link to the hyparchive document, via filters in Intrexx. To be able to search through the stamp fields of a document, which were saved in Intrexx, you can configure the Search function in an application as usual. To do that, create a search configuration and select the stamp fields in the hyparchive data group, which should be indexed by the search engine. Doing so, hyparchive data sets can be searched through by stamp fields using the search function in Intrexx. Another approach is to search using filters in Intrexx applications. Filters, which correspondingly filter data sets in accord with the values in the stamp fields of the Intrexx data groups, on view tables are defined to do that.

2.7.3. Full-text search

Should the users be able to search for keywords in the documents – as well as stamp data –, then the hyparchive full-text is ideal for that. In Intrexx you can directly search through the hyparchive documents, which are managed in Intrexx, and display any hits. There is also the possibility to search for documents in hyparchive, which weren't created with Intrexx, in the portal. To do this the portal users need to also have access to the hyparchive WebClient as well as the hyparchive DocPresenter to open found documents there. The application of both methods will be described in the next section.

2.7.4. Full-text search in Intrexx managed documents




In the following example documents are to be searched for in hyparchive; these documents have a corresponding data set in a hyparchive data group. To begin with, create a view table in the hyparchive data group for the search results. An edit field for the search term is needed as well. Afterwards, open the Dependencies tab in the properties of the view table. Click on Add dependency there, to define a new dependency. A triggering event is needed first. Click on Add event and select "Search" as the control and "onchange" as the event. A filter is needed next, which can be edited by clicking on "Edit filter in expert mode". Copy the following XML fragment between the <filter></filter> element in the editor. 
<exp op="" type="in">
	<arg content="1414DAF1C286E4E92CC553C65615FE60D1500B15" type="fieldguid"/>	
	<arg adapterGuid="8B74A66AB861FC2265829FB96D6985F07C5EBBBB" content="de.uplanet.lucy.server.dghyparchive.connector.rendering.HypArchiveFullTextSearchFilterHandler" searchControlName="textcontrol7D64D21B" singleton="false" type="handlerClass"/>
</exp>
Adjust the filter arguments according to your application: Confirm the dialog now by clicking on "OK" and then publish the application. The search will now be available in the portal.

2.7.5. Full-text search in files that are not managed by Intrexx

With hyparchive web service interface it is possible to search for documents with Groovy action handlers and Velocity templates; the results can then be displayed in Intrexx. To do that you need to program the search selection and the results display yourself, as they are always subject to demand. Parallel to the full-text search it is also possible to search for documents using the stamp and system fields. You can follow the same process as with the full-text search. Only this time a different filter handler is used to search by stamp fields: 
<exp op="" type="in">
	<arg content="1414DAF1C286E4E92CC553C65615FE60D1500B15" type="fieldguid"/>
	<arg adapterGuid="8B74A66AB861FC2265829FB96D6985F07C5EBBBB" content="de.uplanet.lucy.server.dghyparchive.connector.rendering.HypArchiveQueryFilterHandler" singleton="false" stampControls="textcontrol3A8C3723" stampFields="IXTITLE" stampName="IX" systemStampControls="textcontrol38DDAF24" systemStampFields="TIMESTAMP" type="handlerClass"/>
</exp>
Adjust the filter arguments according to your application:

More information

Configure the connection in the Integration module
dg hyparchive in processes