Connector for dg archive - Use in applications

To use the data from dg archive in applications, first create a dg archive 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 dg archive via Intrexx requires an Intrexx standard data group. External data groups are currently not supported by the Connector. The data fields of the data group can then be linked to dg archive stamp fields. For files, a file data field is added to the data group, which is given a special FileHandler class for dg archive.

Select the data group to be linked to dg archive 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 Handler" and the handler "dg archive Handler". 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 show the data fields in the application structure using the main menu "Edit / Show data fields" if the data group is selected there. The title of the field and the previously selected handler class are displayed under the "General" tab. The following specifications are also required:

Configuration

Select the dg archive connection 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 to link data records in Intrexx with documents in dg archive. This requires an Intrexx data field ("Integer" data type), in which the department ID from dg archive can be stored.

Document ID

There must be a unique value to link data records in Intrexx with documents in dg archive. This requires an Intrexx data field ("Integer" data type), in which the document ID from dg archive 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

Controls whether files from Intrexx are saved as a single document or in a document folder in dg archive.

Versionable

Activates the versioning of documents in dg archive.

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. Here, Intrexx data fields or values are assigned to the dg archive stamp fields.

The left side of the dialog lists the dg archive stamps of the previously selected dg archive server, and the right side lists the fields of the Intrexx data group, and if applicable, the fields of a parent data group and user-specific values. For a better overview, the dg archive fields can be filtered by stamp. The dg archive fields and Intrexx data fields can be assigned using the arrow keys. When a data record is saved in Intrexx, the value of the Intrexx data field is automatically saved in the linked dg archive field. Please be sure that the data type in dg archive is compatible with that of the Intrexx data field.

Assign user-defined values

In addition to data fields, user-specific values can also be assigned to dg archive 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 runtime as a unique data record ID for Intrexx and dg archive. Click here for help with this dialog. Calculated values are not saved in Intrexx data fields by default, but only in dg archive fields. For certain purposes it is necessary to save a static value in an Intrexx data field. As a result, after assigning a value to a dg archive field, you will automatically be asked whether the value should also be saved in an Intrexx data 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

Like Intrexx, dg archive also offers the option of defining drop-down lists for data fields. In dg archive, fields with selection lists have the data type "sngsel" or "mltsel" (for lists with multiple selection). Drop-down lists in dg archive can be assigned values from Intrexx data fields or static values. Please note that the value in Intrexx can be used to determine the corresponding entry in the drop-down list in dg archive. If a string Intrexx data field is assigned to the list field, the value stored in it must correspond to a display value in the dg archive 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. In order for Intrexx to determine the document linked to the respective data record in dg archive, it is necessary to store the fields for Department ID and Document ID on each view and edit page that is related to dg archive. The department ID can be determined in the properties of the file field on the Expert tab in the settings (value of the archive.department.id attribute).

To display existing dg archive documents in the Intrexx application requires that corresponding data records be created with the correct department ID and document ID. This can also be done in the hidden area, so that the fields are not visible to the users. If stamp data of a document is changed directly in dg archive, it cannot be automatically synchronized directly in Intrexx without further ado. Consequently, Intrexx automatically updates the fields of a dg archive stamp as soon as the data record is opened on a view or edit page. The user needs to click on "Save" to save the updated data in Intrexx.

Authentication

As the last step of the file data field configuration, the Authentication tab can be used to define which portal user is to be determined for authentication when accessing the dg archive server.

By default the currently logged in portal user will be used. If the user does not have a dg archive session and user name and password were selected as the authentication method in the connection configuration, the user will be prompted to log in to dg archive in the portal. There are use cases in which access to dg archive should always take place via the same dg archive user, regardless of which portal user is currently logged in. This is the case, for example, if there is not a dg archive user for every Intrexx user or if documents from Intrexx should always be saved under the same user in dg archive. To do that a so-called static user can be selected in the dialog. This is an Intrexx user who has been assigned a dg archive user account in the dg archive configuration. A static user can also be set up directly with this dialog. Once such a user is stored in the file data field, all access to dg archive takes place via the data group under this dg archive user account. This means that an interactive login to dg archive in the portal is no longer necessary. This also makes simple Single Sign-On scenarios possible without having to revert to the Kerberos authentication.

dg archive data group handler

Once a file data field for dg archive has been added to an Intrexx data group and configured, the data handler class in the Expert attributes of the data group is automatically set to

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

. This can also be entered later. The dg archive-specific data group handler class is optional, but offers additional functionality in the interaction between Intrexx and dg archive. The stamp values from dg archive are automatically synchronized as soon as an archive data record is loaded on an Intrexx view or edit page. This ensures that an Intrexx portal user always sees the current stamp data from dg archive. In some circumstances it is also possible that stamp data will have been edited in dg archive but the previous value is still saved in Intrexx.

Regional settings

Date/number and currency fields are formatted by dg archive with the format set by the user under Regional settings. dg archive 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, a default language can be defined for dg archive in the configuration of the file data field. In this case, the same language code is used for all dg archive calls. Please note that the format expected by dg archive must be set for date/number and currency input fields in Intrexx.

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 of the file data field, the following settings must be added under 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 further configuration of the connector are available under the "Expert" tab in the properties of the file data field:

• 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 archive 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

  Default language to be used for dg archive web service requests (e.g. de-DE, default country format of the Intrexx user).

• hyparchive.department.id

  ID of the dg archive department.

• hyparchive.department.name

  Name of the dg archive 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

  dg archive 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 archive in portal applications

Authentication

The first time a portal application with a data group containing dg archive file data fields is accessed, the user is prompted to log in to dg archive. This is only necessary once per session and dg archive server. If Windows Integrated Authentication is activated then the user will automatically be logged in upon accessing hyparchive for the first time. No login is required if a static user for dg archive authentication has been stored in the file data field of the data group. After successful authentication, dg archive data can be accessed via the Intrexx application. The portal user has the same functions available with dg archive data groups as with normal Intrexx data groups. In terms of the file operations there are however less special features to consider.

File operations in view tables

dg archive file data fields can be placed in view tables so that files can be opened directly from tables. However, for performance reasons, the default is for no files from dg archive to displayed in file data fields when they are displayed in a view table. To enable this, activate the option "Show files from dg archive in view tables as well" 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

dg archive files are displayed on view pages via the application element View File selection.

Downloading files can also be enabled here.

File operations on edit pages

With the file selection on edit pages, files and documents can be uploaded, changed and saved in dg archive via Intrexx. 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 are added to the existing files in dg archive 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 edit page is saved, the uploaded files are transferred to the dg archive server together with the information in the stamp fields. The new Document ID will be saved in Intrexx.

Existing files can be deleted in dg archive by clicking on "Delete" in the browser.

File operations in drop-down lists

To make maintaining the dg archive stamp fields as easy as possible for the portal user, it makes sense to create drop-down lists on edit pages in Intrexx that are identical with the drop-down lists found in dg archive. The values of dg archive drop-down lists can be determined using the archive FormEdit tool. In Intrexx, a drop-down list can be created on an edit page whose entries reflect those of a dg archive value list. The values can also be defined from another application, from references, or user-defined.

Updating stamp data

Since documents and files are only saved and stored in dg archive, they are always up to date when they are accessed via Intrexx. The stamp data of a document behaves somewhat differently. These are saved both in data fields of the Intrexx data group and in dg archive. This has the advantage that you can also search for stamp fields in Intrexx and access data records without having to access the dg archive server every time. The disadvantage of this approach is that the metadata of a document in dg archive can change over time, while the old values are still saved in Intrexx.

Another way to keep stamp data synchronized between Intrexx and dg archive is by using processes.

Search in dg archive documents

Search options

Documents and files in dg archive data fields are only stored on the dg archive 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 dg archive web service interface offers the possibility to search for documents in dg archive using the dg archive full-text search. The results must then be prepared for Intrexx accordingly, so that a click on a hit opens the document in the dg archive web client or the corresponding data record opens via a filter in Intrexx with the link to the dg archive document.

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 so, create a search configuration and select the stamp fields in the dg archive data group that are to be indexed by the search engine. Afterwards, dg archive data records can be searched for stamp data 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

If you want to search for keywords in the documents in addition to the stamp data, you can use the dg archive full-text search. You can search for dg archive documents managed in Intrexx directly in Intrexx and display the results. The portal can also be used to search for documents in dg archive that were not entered via Intrexx. In the latter case, portal users also need access to the dg archive WebClient or DocPresenter in order to open documents found there. The implementation of both approaches is described in the following.

Full-text search in Intrexx managed documents

In the following example, a search is to be carried out in dg archive for documents for which there is a corresponding data record in a dg archive data group. To do so, create a view table in the dg archive 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 here, which corresponds to the document ID in dg archive. The entries below refer to the second <arg> element.

• adapterGuid

  The GUID of the dg archive file data 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

The dg archive web service interface can also be used to search for documents in Groovy action handlers and Velocity templates and to display the results 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 here, which corresponds to the document ID in dg archive. The other entries refer to the attributes of the second <arg> element.

• adapterGuid

  The GUID of the dg archive file data 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