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

In order to be able to save stamp data and documents in dg archive via Intrexx, an Intrexx standard data group is required. 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 receives 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":

• Department ID

  Integer" data type (creates an integer data field)

• Document ID

  Integer" data type (creates an integer data field)

• Title/Name

  Short text" data type (creates a string data field)

File fields

Then create another data field with the data type "File". 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 the field 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 on 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(data type "Integer") 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(data type "Integer") 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 permanently selected or dynamically determined via an Intrexx data field(data type "Integer") that contains the type ID.

Document note

If the document type "From Intrexx data field" is selected, a data field from the application can be selected here, in which comments on the document are saved.

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

Then switch to the Field assignment tab. Intrexx data fields or values are assigned to the dg archive stamp fields here.

On the left side of the dialog, the dg archive stamps of the previously selected dg archive server are listed, on the right the fields of the Intrexx data group, 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. With the arrow buttons, dg archive fields and Intrexx data fields can be assigned. When saving a data record in Intrexx, the value of the Intrexx data field is automatically saved in the linked dg archive field. Please note 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 helpful, for example, if the same value is always to 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. You can find help on this dialog here. 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. Therefore, 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 Save value in data field setting can be activated here. Click "OK".

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

Assign drop-down lists

Like Intrexx, dg archive also offers the option of defining selection lists for data fields. In dg archive, fields with selection lists have the data type "sngsel" or "mltsel" (for lists with multiple selection). Selection 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 selection 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 selection list. And please note that this is case sensitive.

View and edit pages

The usual data field controls on view and input pages are available for viewing and editing 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 input page with dg archive reference. 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).

In order to display existing dg archive documents in the Intrexx application, corresponding data records must 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 users. If stamp data of a document is changed directly in dg archive, it cannot be automatically synchronized directly in Intrexx without further ado. Therefore, Intrexx automatically updates the fields of a dg archive stamp as soon as the data record is opened on a view or entry page. In order to save the updated data in Intrexx, the user must then click on "Save".

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 directly setup with this dialog. As soon as 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

As soon as 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 input page. This ensures that an Intrexx portal user always sees the current stamp data from dg archive. Under certain circumstances, it can happen that stamp data has been changed in dg archive and the previous values are still saved in Intrexx.

Regional settings

Date/number and currency fields are formatted by dg archive with the format set by the user under Country settings. dg archive requires the full language/culture code (e.g. de-DE or en-US instead of de or en). The formats for 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 is set in Intrexx for date/number and currency input 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 data 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 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 further configuration of the connector are available on 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 dgarchive 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 input 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 Integrated Windows Authentication is active, the user is automatically logged in on first access. A login is not 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 to open files directly from tables. However, for performance reasons, no files from dg archive are displayed in file data fields by default when they are displayed in a view table. To do this, activate the option "Also display files from dg archive in view tables" in the file data field configuration. If documents are to be downloaded directly from tables, this must 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 File selection view.

Downloading files can also be enabled here.

File operations on edit pages

With the file selection on input 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 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 and dropped onto the file control and thus automatically uploaded to the Intrexx server. When the input 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 the browser by clicking on "Delete" in dg archive.

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 identical selection lists for selection lists in dg archive on input pages in Intrexx. The values of dg archive selection lists can be determined using the archive FormEdit tool. In Intrexx, a selection list can be created on an input 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 accordingly for Intrexx, so that when you click on a hit, the document opens in the dg archive web client or the corresponding data record is opened 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 must make an adjustment in the "moduleConfig.xml" configuration file.

The "moduleConfig.xml" file can be found in the following location: <portal directory>/internal/search/moduleConfig.xml

Search 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 search for stamp fields of a document saved in Intrexx, you can configure the search in an application as usual. To do this, 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 the search via 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 documents for which there is a corresponding data record in a dg archive data group. To do this, create a view table on the dg archive data group for the search results. Additionally, an edit field is required for the search results. Then open the properties dialog of the view table and switch to the Dependencies tab . Click on "Add dependency" to define a new dependency. A triggering event is needed first. To do this, click on "Add event" and select the input field as the control and onchange as the event, for example. A filter is needed next, To do this, click on "Edit filter in expert mode". Copy the following XML fragment into the editor within the <filter></filter> element:

            <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 other details refer to the attributes of 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.

Now confirm all dialogs by clicking on "OK" and 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 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 specifications 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