Connector for dg hyparchive - Use in applications

To use the data from dg hyparchive in applications, first create a dg hyparchive connection in the "Integration" module. A data group can then be configured accordingly as described below.

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.

Select the data group that is to be connected to dg hyparchive in the application structure and create at least the following data fields via the main menu "New / Data field" option:

• Department ID

  Data type: Integer.

• Document ID

  Data type: Integer.

• Title/Name

  Data type: String.

File fields

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

Select the option "Intrexx handlers" and then "dg hyparchive Handler" from the drop-down list. Then click on "OK" and complete the creation of the file data field by also clicking on "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 using the "Edit / Show data fields" main menu when the data group is selected. The title of the field and the previously selected handler class are displayed on the "General" tab. The following specifications are also required:

Configuration

Select the dg hyparchive handler class here.

Department

Based on the chosen configuration all available departments will be listed, for which the recorded users have access permission. Department ID There must be a unique value, so that data sets in Intrexx can be linked with documents in hyparchive.

Department ID

There must be a unique value, so that data sets in Intrexx can be linked with documents in hyparchive. For this, an Intrexx data field with the “integer” data type is required where the Department ID can be stored.

Document ID

There must be a unique value, so that data sets in Intrexx can be linked with documents in hyparchive. For this, an Intrexx data field with the “integer” data type is required where the Document ID can be stored.

Document name

Select a data group field where the name of the document is saved.

Document type

A document type must be defined for the documents. This can either be selected as a constant or defined dynamically via an Intrexx data field for the "Type ID" (data type “integer”).

Document note

If the document type "From Intrexx data field" is selected, you can select a data field from the application that contains comments for the documents.

Record as a file folder

Determines whether files from Intrexx should be stored as a single document or as a folder in hyparchive.

Versionable

Activates versioning in dg hyparchive.

Comment

A data field can be selected here where comments for versions can be recorded.

Stamp fields

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.

On the left side of the dialog, the dg hyparchive stamps of the previously selected dg hyparchive server are listed, and on the right side, the fields of the Intrexx data group, or possibly, the fields of a parent data group, and user-specific values. 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.

Assign 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.

Assign 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.

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.

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.

dg hyparchive data group handler

As soon as a data field for dg hyparchive is added to an Intrexx data group and then configured, the data handler class in the expert attributes of the data group is automatically changed to:

de.uplanet.lucy.server.dghyparchive.connector.rtdata.RtDataGroupTableHypArchive

. This can also be entered later. 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.

Regional settings

Date/number and currency fields are formatted by dg hyparchive with the format set by the user under Regional settings. dg hyparchive requires the full language/culture code in this case (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.

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 file data field properties, 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)

Expert settings

The following settings for the further configuration of the connector are available on the "Expert" tab in the file data field properties:

• hyparchive.sap.archive

  Flag whether documents should be archived with the SAP ArchiveLink

• hyparchive.sap.archive.id.field.guid

  GUID of the data field for the SAP ArchiveLink ID.

• hyparchive.cfg.guid

  The GUID of the dg hyparchive configuration.

• hyparchive.container.doc.class

  Class for archive documents (default is DC_FILE).

• hyparchive.container.document

  Determine whether the document is a single or archive file (True/False).

• hyparchive.default.language

  The default language to be used for hyparchive web service requests (e.g. de-DE, the default is the regional setting of the Intrexx user).

• hyparchive.department.id

  ID of the dg hyparchive department.

• hyparchive.department.name

  Name of the dg hyparchive department.

• hyparchive.deptid.field.guid

  Field GUID for the Department ID.

• hyparchive.docid.field.guid

  Field GUID for the Document ID.

• hyparchive.docName.field.guid

  Field GUID for the Document Name.

• hyparchive.docType.id

  hyparchive Document Type ID.

• hyparchive.file.doc.class

  Class for single files (default is DC_DOSFILE).

• hyparchive.filename.as.docname

  Determine whether the file name should be used as the document name.

• hyparchive.impersonation.guid

  Intrexx user GUID for the login as a static user.

• hyparchive.onlyUpdatePropertiesWithFileField

  Updates the stamp fields when saving even if there is no file field on the edit page or is added to the update in processes (type: boolean, default: false).

• hyparchive.showindatarange

  Determine whether files should be displayed in view tables.

• hyparchive.stamp.field.mapping

  Stamp field assignment.

• hyparchive.version.comment.field.guid

  Field GUID for comments when a file is versioned.

• hyparchive.versionable

  Determine whether documents are versionable.

dg hyparchive in portal applications

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.

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.

File operations on view pages

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

Downloading files can also be enabled here.

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 functions in standard Intrexx file fields are available for this.

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. However, it is also possible to replace files.

Additionally you can determine the maximum number of files per data set that can be saved. as well as the maximum size of a file. In addition, there are advanced functions for uploading files, which affects the behavior of the control in the portal. In the browser files can be dragged to the file control, which automatically uploads the file 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".

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 also be defined from another application, from references, or user-defined.

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.

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

Search in hyparchive documents

Search options

Documents and files in hyparchive data fields are only stored on the hyparchive server. This means 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 in Intrexx. 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.

Intrexx search

Index stamp fields with the Intrexx search

So that the Intrexx search can find the stamp fields of a document, these must be indexed by the Intrexx search. To do this, you need to make an adjustment in the configuration file "moduleConfig.xml".

You can find the file "moduleConfig.xml" here: <portal directory>/internal/search/moduleConfig.xml

Look for the following entry in the "moduleConfig.xml" file:

<fileHandler class="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveFileHandler" adapter="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveBusinessAdapterQueryEngine" adapterNeedsSolrIndex="false"/>

Change "false" to "true".

Original

<fileHandler class="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveFileHandler" adapter="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveBusinessAdapterQueryEngine" adapterNeedsSolrIndex="false"/>

After the change

<fileHandler class="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveFileHandler" adapter="de.uplanet.lucy.server.dghyparchive.connector.HypArchiveBusinessAdapterQueryEngine" adapterNeedsSolrIndex="true"/>

Now restart the Intrexx services.

Configure search in applications

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.

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 implementation of both approaches is described in the following.

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. Additionally, an edit field is required for the search results. 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:

• content

  In the first <arg> element, enter the data group field GUID, which corresponds to the Document ID in hyparchive. The entries below refer to the second <arg> element.

• adapterGuid

  The GUID of the hyparchive file field.

• searchControlName

  Enter the name of the input control for the search expression here.

• Domains (optional)

  This tells the filter which department it should search in for documents. The various departments are separated by a comma.

Confirm the dialog now by clicking on "OK" and then publish the application. The search will now be available in the portal.

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. The instructions to call the search and display the results in this approach must be programmed individually, since they are always specific to the requirements. Please see the M-Files user manual for more information on how to use the M-Files REST API for the search.

Stamp search

Parallel to the full-text search it is also possible to search for documents using the stamp and system fields. To achieve this, proceed the same as for 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:

• content

  In the first <arg> element, enter the data group field GUID, which corresponds to the Document ID in hyparchive. The other entries refer to the attributes of the second <arg> element.

• adapterGuid

  The GUID of the hyparchive file field.

• stampName

  Enter the name of the stamp that should be used in the search.

• stampControls

  Enter the names (separated by a comma) of the input control for the search term.

• stampFields

  Enter the names of the stamp fields (separated by a comma). The order needs to correspond to that of stampControls.

• systemStampControls

  Enter the names (separated by a comma) of the input control for the system stamp fields.

• systemStampFields

  Enter the names of the system stamp fields (separated by a comma). The order needs to correspond to that of systemStampControls.

• Domains (optional)

  This tells the filter which department it should search in for documents. The various departments are separated by a comma.

More information

General

Create and edit connection in the "Integration" module

Use in processes

Troubleshooting