Open Documentation Menu

Preparing the installation

Before you install d.3one, it is helpful to analyze and plan some aspects in advance. You may want to consider the following aspects, for example:

  • Plan how to install d.3one and the core apps into your IT infrastructure, e.g. to ensure scalability.

  • You must run the d.3one setup as administrator.

  • Initially, perform the installation in a test environment.

  • Test the software in the test environment based on real-life scenarios.

  • Create a backup of all servers, data and configurations in the production environment before the installation.

  • Plan the time of the installation and distribution in agreement with the departments of your organization.

An installed and operational d.3 repository is required which you can then prepare for the d.3one installation.

As a technical prerequisite for a clean installation under Windows Server 2016 and Windows Server 2019, you must first specify a default browser in order to download tools from the Internet, if applicable. We recommend to use Internet Explorer.

This topic with the following chapters provides you with support for the planning and performing of the preparatory tasks:

Once the preparation is completed, you can start with the installation.

See also:

Installing the core apps and essential administrative tasks

Before running the setup to install the d.3one integrating application, you need to install the core apps. In this chapter you can learn which aspects to be considered while installing and configuring in order to make the additional preparations for d.3one in the context of d.3ecm. For information about installing the core apps, see the d.velop software manager manual. For more information about configuring the infrastructure components, see the configuration guidelines for d.velop infrastructure components.

See also:

Preparing the clean installation of d.3one

If you install d.3one for the first time and you already use Internet Information Services (IIS), you need to modify the binding prior to installing d.3one.

Internet Information Services (IIS) already exist:

If a site in IIS has a binding on port 443, then this binding must be deleted before installing d.ecs http gateway. Otherwise, the port is already in use so that d.ecs http gateway cannot be started correctly. Existing applications with a binding on port 443 must use a different port, if applicable. You can also register the application as app in d.ecs http gateway, provided the app should still be accessed on port 443. For more information see the Configuration guidelines for d.velop infrastructure components.

This is how it works

  1. Close all applications using the port 443.

  2. In IIS Manager, open the default web site (Default Web Site).

  3. Select Bindings under Edit Site.

  4. Delete the port 443 for this site.

Once the binding is deleted, install the core apps.

Once the required components are installed, you can proceed with the preparing tasks for installing d.3one and then run the d.3one setup.

See also:

Preparing the update installation of a previous version

You can update d.3one to the Current version only, if you have already installed version 1.7.0. For earlier versions of d.3one, you need to follow the following installation order.

  1. Update the software to version 1.4.0.

  2. Then update to version 1.5.0. When updating to version 1.5.0, you need to take the migration steps into consideration which are described in this chapter in the administration manual for version 1.5.0.

  3. Update to version 1.6.0.

  4. Update to version 1.7.0.

Finally, you can update your environment to the d.3one Current version.

d.velop infrastructure components (d.ecs infrastructure)

With d.velop software manager, you can install the required d.velop software components. Make sure to install the appropriate infrastructure components (d.ecs infrastructure). For more information see d.3one (application server).

Warning

In combination with d.3one version 1.7.0, it is required to use d.3 server since version 8.1.0 Hotfix 5. You need to make sure that d.3 server and d.3one use the same d.ecs http gateway app. You also need to ensure that all d.ecs jstore instances operate in the cluster.

See also:

Latest version of d.3one

You can find main version of d.3one in the d.velop service portal. You can get information about updated versions such as hotfixes (HF) at the following locations and obtain the latest setup there:

d.3one is continuously enhanced and also provides new functions. You can use the new functionality in the Current version.

For more information about the releases visit the d.velop service portal and see your d.velop partner.

Preparing the d.3 server

To properly run the various d.3one integrations, certain requirements must be met on the d.3 system. Among these requirements are the seamless collaboration between a d.3 repository and the d.3one integration, for which certain requirements must be met and settings must be applied. This is, e.g., the installation of the latest version of d.3 server and certain settings to be applied in the repository.

This topic describes which measures you should take and how to prepare the server with d.3 server for running d.3one.

Warning

In combination with d.3one version 1.7.0, it is required to use d.3 server since version 8.1.0 Hotfix 5. You need to make sure that d.3 server and d.3one use the same d.ecs http gateway app. You also need to ensure that all d.ecs jstore instances operate in the cluster.

Warning

All measures and settings must be successfully applied before running the setup. If not all preparatory tasks were performed or settings were not configured, then this may lead to issues when running the setup program later on.

If you already have a d.3 system, you should first update the database tables in d.3 server using the update script as described under Running the JPL update script. This step can be skipped when performing a clean installation of d.3 server. Moreover, make sure that d.3 server is accessible in both directions on port 3400.

Optionally, you can set the faceted search function for each category in the d.3 administration to provide your users with a simple option to find in an complex result list more quickly what they are looking for. Find out more in the chapter Configuring the faceted search function.

See also:

Running the JPL update script

For d.3one properly running, at least d.3 server version 8.1.0 is required. For the smooth collaboration between d.3one and an already existing d.3 repository, the database tables must be updated.

Warning

It is mandatory to execute the JPL update script when updating d.3 server which is valid for the d.3 server version.

If you want to specify several d.3 repositories in d.3one, you must perform the update operation using the JPL update script for each d.3 repository.

Associating generated d.3 formats to file types

You can store and manage at least two different file formats for a single document in a d.3 repository. A document consists of an original file (e.g. Microsoft Word or AutoCad file) needed for additional editing and a so-called "dependent" file. This "dependent" file is generated in a specific format (e.g. as PDF format) so that the generated file automatically represents the original file in the d.3 repository. You can use a generated PDF file for a Word document to quickly view and print it in an app.

A generated file reflects the master or original file. The generated file has no properties of its own and is managed by the same document ID as the original file.

Generally, the file extension for generated files consists of two parts (e.g. *.t1). Usually, the file extension consists of a letter followed by a digit. In the d.3 Administration, you need to specify the file extensions for the d.3 repository, which are to be used to store documents into the d.3 repository (option File name Extensions for Dependent Documents). Apart from managing these files, you can also specify in d.3 admin which file name extensions for the file type can be downloaded (e.g. to display them). The so-called dependent file is associated to a specific file format by the number (position) in the d.3 configuration dialog (option File Extensions for visualizing Dependent Documents). If there is no association defined, the original file extension of the dependent file is used (e.g. t1). You can define the following associations for the generated file, for example:

File name Extensions for Dependent Documents

File Extensions for visualizing Dependent Documents

Effects for downloading

No.

Value

No.

Value

Current file name

File name after download

1

or

1

txt

Document1.or

Document1.txt

2

t1

2

tif

Drawing23.t1

Drawing23.tif

(...)

(...)

(...)

(...)

(...)

(...)

12

x1

12

zip

Infoleaflet77.x1

Infoleaflet77.zip

13

z1

13

---

Information49.z1

Information49.z1

This association only affects the download of documents.

For additional information about d.3 admin and d.3 config see the respective manuals.

Configuring the faceted search function

The user can use a faceted search functionality. With the faceted search the user can refine complex search results by selecting facets to reduce the complexity of the result list. The faceted search is useful for huge sets of data in the d.3 repository.

In order to achieve optimal results for the users in your organization, it is recommended to collaborate and plan with representatives from the departments which properties should be facets. Not every category’s property is suitable for faceting. The doc_id property, for example, is not suitable for the faceting function because this property is used for each document in the result list and thus generates its individual facet value.

Connecting to the license server

The server running d.ecs license server manages the licenses for all d.velop products you purchased. For additional information about d.ecs license server and configuration see the d.ecs license server manual. The d.3one integrations need an individual license. If you have obtained a language pack in addition, also specify the language in d.ecs license server.

Warning

The server running d.ecs licence server must be accessed using the DNS name "d-velop-license" and that the firewalls must not block the port 3489 for UDP and TCP.

See also:

Authentication procedures

The authentication methods are provided by d.ecs identity provider. For each d.3 repository, the same instance of d.ecs identity provider must be configured, since the user can only authenticate himself or herself at a single d.ecs identity provider instance.

If you set the option for enabling single sign-on in d.ecs identity provider (e.g. Kerberos), your users can use the single sign-on (SSO) functionality. For more details, see the Configuration guidelines for d.velop infrastructure components in the d.ecs identity provider articles.

Issuing a domain web server certificate for d.ecs http gateway

In this chapter, you can learn how to create a web server certificate without the IIS role that is valid across the domain and how to export the web server certificate including the private key. A certificate is needed to ensure a secure HTTP connection (HTTPS).

The advantage of a certificate which is valid across the domain is that the certificates on the computers can always be verified within the domain due to the certificate chain. Domain certificates in the certificate chain are automatically provided to each computer which joins the domain at a later point in time.

If you use the d.3 mobile app on mobile devices, you need a certificate of an official certification authority.

The creation of a certificate consists of two tasks.

  1. To create a certificate template is the preparation and done only once.

  2. A certificate must be created for each web server address.

An existing certificate only has to be recreated if the properties of the certificate have changed, because you can use the same certificate on multiple computers.

Creating the certificate template

  1. Start the management console (mmc) with administrator rights on the computer with the certification body for your domain.

  2. Add the Certificate Templates snap-in.

  3. Select the Web Server template.

  4. Choose Duplicate Template in the context menu.

  5. In the Properties of New Template dialog box, enter a name for your new certificate template under Template display name on the General tab.

  6. Activate the Allow private key to be exported checkbox on the Request Handling tab. Thus, you make sure that the certificate including the private key can be exported and be provided for d.ecs http gateway later.

  7. On the Cryptography tab, you can make optional adjustments that affect the properties of the certificates issued with this certificate template.

  8. Enter a value under Minimum key size (the recommended value as of January 2020 is 2048) and finish creating the certificate template.

Warning

To ensure sufficient security, the key size (which is also referred to as the key length) must comply with the current guidelines for key sizes in asymmetrical encryption algorithms. At minimum, the certificate must use SHA-256 as the signature hash algorithm.

As soon as the certificate template is created, you must enable it.

  1. Start the management console (mmc) with administrator rights on the computer with the certification body for your domain.

  2. Add the Certification Authority snap-in.

  3. Choose Certificate Templates.

  4. In the New context menu, choose the Certificate Template to Issue entry.

  5. Select the certificate template created by you in the list of certificate templates.

  6. Choose OK to activate the selected certificate template.

The certification template was enabled only for this certification authority.

Creating a certificate

In this step you learn more about the required tasks to create a web server certificate which you can use for d.ecs http gateway.

If you create a certificate for third-party software, you may specify additional certificate properties.

Note

To create a web server certificate, you do not necessarily have to be logged in on the computer on which the certification authority is installed. A web server certificate can be created on any computer.

  1. Start the management console (mmc) with administrator rights.

  2. Add the Certificates snap-in for the Computer account area.

  3. Choose Personal.

  4. In the All Tasks context menu, choose the Request New Certificate entry.

  5. Enable the checkbox next to the name of the certificate template created by you.

  6. Click the link below your certificate template to go to the Certificate Properties dialog box and enter the missing properties for the certificate.

  7. On the Subject tab in the Certificate Properties dialog box, enter the required certificate properties for Subject name and Alternative name.

There are certain certificate properties visible in d.ecs http gateway. In order to display these certificate properties, you need to specify these when creating the certificate. The overview represents the mapping of the terms between the d.ecs http gateway and Microsoft terminology.

d.ecs http gateway

Certificate property

Sample value

Alias/type

Data type

Country code (2 characters)

Country/Region

DE

C

String (2 characters)

Country/Region

Status

North Rhine-Westphalia

S

String (128 characters)

City

City

Gescher

L

String (128 characters)

Company

Organization

d.velop AG

O

String (64 characters)

Department

Organizational unit

<department>

OU

String (64 characters)

Host name of server

Common name

<base address>

CN

String (64 characters)

Host name of server

Alternative Name

<base address>

DNS

String (64 characters)

Note

In the Key options area on the Private Key tab, you can select a key size that differs from the minimum key size and use the Make private key exportable checkbox to ensure that the private key can be exported later.

Choose Register to start the creation of the certificate. Once the certificate is created, it must be exported.

  1. Open the created certificate by double-clicking on it.

  2. To export it, go to the Details tab and click Copy to File.

  3. Select the Yes, export the private key radio button and enter a password to protect the private key.

Warning

The password can contain only characters from the CP 850 character set.

You must specify this password when importing the certificate in d.ecs http gateway. It is recommended not to use the password in another context.

The certificate created is selected in the setup when installing d.3one.

See also:

Enabling HTTPS for a secure communication (optional)

The communication between the integrating applications as well as the browser and the d.ecs http gateway app is in general encrypted using HTTPS. However, the d.ecs http gateway app and the instance of an app communicates unencrypted using HTTP. The apps hosted in Internet Information Services (IIS) are an exception from this since the communication is already encrypted using TLS (Transport Layer Security protocol). You can encrypt the communication between the d.ecs http gateway app and the app instances with a certificate, which uses the TLS protocol.

In this chapter you can find a step-by-step instruction how to encrypt the communication. The protocol used correspond to the current security standard while SSL (Secure Socket Layer) is used as a synonym for TLS.

Self-signed certificate are considered as insecure in general and must not be used if you want to configure a secure connection.

This is how it works

First, you need to enable TLS in the respective apps and assign the fixed port to the app. Do the following:

Enabling TLS in the apps d.ecs repo, d.ecs process portal, d.ecs identity tunnel, d.ecs file container, d.ecs pdf:

  1. Go to the folder conf in the installation directory of the app.

  2. If the appsettings.config file does not yet exist, create the file and copy the content from the file appsettings.config.template into the file.

  3. Open the appsettings.config file.

  4. Set the value protocol to https (e.g.: <add key="protocol" value="https"/>).

  5. For the value baseaddress, specify the complete URI with the host name of the computer with the d.ecs app (e.g.: <add key="baseaddress" value="https://d3one.contoso.local/"/>). If this value is empty, the base address (System.BaseUri) is used automatically.

  6. For the value hostname, specify the host name of the computer with the d.ecs app (e.g.: <add key="hostname" value="d3one.contoso.local"/>). If this value is empty, the hostname of the computer is automatically determined.

  7. Set the values port to a fixed value (e.g.: <add key="port" value="4010"/>).

  8. Save the file.

  9. Restart the service d.ecs repo, d.ecs process portal respectively d.ecs identity tunnel.

For the next step you need the hash value of the certificate to be linked. You can use the same certificate you already use in IIS. Do the following:

  1. Start the Windows command prompt as administrator.

  2. Enter the command netsh http show sslcert ipport=0.0.0.0:[Port], while you replace [Port] by the port number, which you specified during the installation of d.3one (default value: 3401).

  3. The hash value is displayed under Certificate Hash.

If you want to use a different certificate, you can determine the hash value (thumb print) in the properties of the certificate. Remove any space characters.

Besides this hash value, an application ID (appid) is also needed. You can use as application ID any valid GUID in the format "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX".

Using both values you can now link the certificate to the app port. Do the following:

  1. Start the Windows command prompt as administrator.

  2. Enter the command netsh http add urlacl url=https://*:[Port]/ user=[User], while you replace [Port] by the port number and [User] by the user running the app (e.g. SYSTEM).

  3. Then, enter the command netsh http add sslcert ipport=0.0.0.0:[Port] certhash=[hash] appid={[appid]}, while you replace [Port] by the port number, [hash] by the saved hash value and [appid] by the application ID mentioned above.

  4. Confirm the command.

The commands may look like this:

netsh http show sslcert ipport=0.0.0.0:3401
netsh add urlacl url=https://*:4000/ user=SYSTEM
url=https://*:4000/ user=SYSTEM
netsh http add sslcert ipport=0.0.0.0:4000 
certhash=e31c06568e4b222a92c8434eaa770b26f09a31a3 appid={2131f4cd-d05b-4308-9af1-9caa44b2c74a}

Note

If the port was successfully linked, it is listed in the command prompt when using the command netsh http show sslcert. You can also directly display the linked port using the command netsh http show sslcert ipport=0.0.0.0:[Port], while [Port] is to be replaced by the port number.

Restart the respective apps to make sure that the apps use HTTPS instead of HTTP when registering at the d.ecs http gateway app.

You can verify in the d.ecs http gateway administration, how the apps registered at the d.ecs http gateway app. Do the following:

  1. Open the administrative interface of the d.ecs http gateway app using https://<computer name>:4200.

  2. Open Registered apps.

  3. Select an app.

  4. Under Registered app instances, you can determine the URL used of the respective app instance.

Opening ports in the firewall (optional)

If you want to install the product-specific apps and the core apps, e.g. d.ecs http gateway, on different server, the opening of ports for the apps is essential for you.

You have the option and it is recommended to assign each product-specific app a fixed port.

If you decide to open fixed ports in the firewall, you must assign the d.3one apps d.ecs repo, d.ecs process portal, and d.ecs identity tunnel, d.ecs file container and d.ecs pdf a fixed port number.

This is how it works

  1. Go to the folder conf in the installation directory of the app.

  2. If the appsettings.config file does not yet exist, create the file and copy the content from the file appsettings.config.template into the file.

  3. Open the appsettings.config file.

  4. Set the value for port to a fixed value (e.g.: <add key="port" value="4010"/>).

  5. Save the file.

  6. Restart the respective services.

For apps hosted in IIS, the port is specified when installing d.3one.

For more information about assigning ports for the core apps, see the appropriate product manual.

See also: