Running the setup by using Custom setup in the setup wizard

The setup wizard runs you through setting up your database, configuring email settings, configuring the user registry, and registering applications. The wizard detects and prompts you to set up the applications that you installed.

Before you begin

For new installations, if you do not want to use the default port numbers, you must change them before you use the setup wizard. For more information, see Changing the port numbers for the application server.

If you are using an enterprise database such as Db2®, Oracle, or Microsoft SQL Server, you must create the databases beforehand. For more information, see: When you create the databases, you do not need to create the database tables by running the repotools command. On the Configure database page of the wizard, click Create tables to create the database tables.

Ensure that you started the server by following the instructions in Deploying and starting the server.

If you are using Internet Explorer to run the setup wizard and your databases and applications are on separate servers, security certificates must be installed on those servers. For more information, see Installing a security certificate.

About this task

Complete each step in this wizard to configure the Jazz Team Server and the applications you installed. If you want to make changes after setup is complete, you can return to the wizard and start over.

Procedure

Note: If you are running the wizard to set up distributed applications, complete the following steps in order:
  1. Install the Jazz Team Server application and trial licenses on the first server. Start the first server but do not run the setup wizard on the server.
  2. Install other ELM applications on the second server or on a server for every application. Start the servers, but do not run the setup wizard.
  3. Run the setup wizard on the first server (with the Jazz Team Server application). When you get to the Register Applications page of the setup wizard (see step 8), provide the discovery URL of the applications that are installed on the other servers.

  1. Point your web browser to the following address: https://fully_qualified_hostname:9443/jts/setup
    Note: Default port number on IBM i systems is 29443.
  2. The Jazz Team Server login page opens.
    Note: If Jazz Security Architecture SSO is enabled in the Jazz Team Server, disregard this step because the login page is displayed later (in step 8.a).
    • In the User ID and Password fields, type ADMIN in uppercase letters. Then, click Log In.
    • If you enabled applications to use Lightweight Directory Access Protocol (LDAP) or federated file-based registry on WebSphere® Application Server, do not use ADMIN as a value for the User ID and Password fields. Instead, log in as an LDAP registered user who has JazzAdmins privileges. The LDAP user or group must be mapped to the repository group. For mapping security roles to a user or repository group, see Deploying applications for the IBM Engineering Lifecycle Management on WebSphere Application Server.
    • For WebSphere Application Server on z/OS® with RACF® security or WebSphere Application Server on IBM i with local OS authentication, use a user ID that has JazzAdmins privileges on the system. Default user ID and password on IBM i are JTSADMIN and JTSADMPWD.
  3. On the Welcome page, there are two options available for setting up the server: Express setup and Custom setup.
    Note: If Jazz Security Architecture SSO is enabled in the Jazz Team Server, Express setup is disabled.

    For information about Express setup, see Running the setup by using Express setup in the setup wizard. For production environments, select Custom setup and click Next.

  4. The Introduction page provides some high level information about the steps in the wizard. Click Next to continue.
  5. On the Configure Public URI page, provide a Public URI Root that is of the form https://fully_qualified_hostname:9443/jts and select the check box to confirm that you read and understand the recommendations. Click Test Connection. After the test is successful, click Next.
    Note: A fully_qualified_hostname is the host name along with the DNS domain reference of the machine on which the Jazz Team Server is installed.

    An example of a good fully_qualified_hostname is clmwb.example.com.

    Examples of bad fully_qualified_hostname are localhost or an IP address.

  6. On the Configure Database page, provide information to set up a connection to the database.
    • Database Vendor: Select from the list of supported database vendors.
    • Connection Type: Select J2EE if you manage your database connection by the J2EE container in WebSphere Application Server. You must provide the J2EE data source name. JDBC connection type does not involve the container and Jazz Team Server connects to the database directly and manages the connection pooling. For JDBC connection type with databases other than Derby, you must provide the JDBC password and location. Derby database does not require a password.

    If you are using the Derby database, you do not need to change the default values, and you are not prompted to create database tables.

    If you change the default values or set values for an enterprise database like Db2, Oracle, or SQL Server, click Test Connection to make sure that the connection is configured correctly.

    If you did not previously use repotools to create the database tables, you might see a warning that the database exists but that it does not contain any tables. To create the tables, click Create tables. You might have to wait several minutes for the command to finish.

    If you tested the connection and you see no warnings or errors, click Next.

  7. On the Enable E-mail Notification page, enable or disable email notifications. If you choose to enable notifications, you need to provide information about your email server and test the connection to the email server. After the test was successful, click Next to continue.
  8. On the Register Applications page, the wizard detects the applications that were installed along with the Jazz Team Server. It might take a minute for each application to be discovered and added to the list of applications to register. The wizard does not detect the applications that are installed on a different server; you must manually add these applications (see step d).
    1. If Jazz Security Architecture SSO is enabled in the Jazz Team Server, ensure the Jazz Authorization Server is started and running, and then complete the Authorization Server URL, Administrator User ID, and Administrator Password fields. Click Test Connection to verify the settings.
      Important: Once an application is configured with Jazz Security Architecture SSO enabled, it cannot be simply disabled; you cannot revert to a different single sign-on authentication method.

      Ensure that your browser is not blocking pop-up windows. The Jazz Authorization Server uses a pop-up window for logging in.

    2. Optional: If you do not want to register an application, click the Close icon to the far right of the application name.
      Typically, you register all applications; however, you might not want to register one or more applications in the following situations:
      • You downloaded and deployed all applications, but you do not intend to use all of them.
      • You do not have licenses that allow access to an application.
      • You are configuring this Jazz Team Server application as a stand-alone floating or token license server.
    3. Verify the Application Type and Discovery URL of the installed applications. The wizard creates default pre-authorized functional User IDs for each application.
      What is the Discovery URL?: The discovery URL is the service contribution resource (SCR) URL of an application. In general, the SCR URL is formed by adding /scr to the Public URI for the application. For example, if the Public URI for the Change and Configuration Management application is https://fully_qualified_hostname:9443/ccm, the corresponding SCR URL must be https://fully_qualified_hostname:9443/ccm/scr. For a locally installed application, this URL and a functional user ID are completed by the setup wizard.
    4. Optional: To add an application that is installed on a different server, click Add Application and provide the application name and discovery URL.
      After you provide the application name and discovery URL, the Functional User ID is generated and entered automatically. The functional user ID is used to run tasks in the background. The functional user ID does not have to exist in the external user registry or as a user in the repository; if the user ID does not exist in the repository, it is automatically created.
    5. Click Register Applications.
      Note: The wizard creates friend relationships, registers the applications, and generates a consumer key and secret for each application.
    6. After registration is successful, click Next to configure the registered applications.
      Note: Notice that the menu on the left now lists the registered application along with substeps.
  9. On the Setup User Registry page, provide the following information.
    1. If Jazz Security Architecture SSO is enabled on the Jazz Team Server, instead of choosing between different types of user registries, the only options are to choose whether to configure synchronization with an LDAP or an SCIM provider.
      • If the Jazz Authorization Server is configured with an LDAP user registry, to configure the Jazz Team Server with automatic synchronization with the same registry, select LDAP, LDAP/SDBM, or SCIM. Depending on your selection, the LDAP (either LDAP or LDAP/SDBM) or SCIM configuration fields are displayed.
        1. Complete the configuration fields.
        2. Verify the synchronization properties by clicking Test Connection.
        3. Click Save and Log In. Then, log in as the Jazz administrative user for your organization.
      • If you do not enable automatic synchronization by selecting LDAP or SCIM, you must create an administrative user for yourself on the Jazz Team Server.
        1. Complete the form by using the same user ID that you used to log in as the Jazz administrator. For example, if you are using the default localUserRegistry.xml configuration file on the Jazz Authorization Server, in the User ID field, type clmadmin. You do not specify a password for the Jazz administrator.
        2. Click Save and Log In. Then, log in as the Jazz administrative user that you created in the previous step.

      The Setup User Registry page opens and displays the licenses available to assign to the administrative user. Go to step e.

      For more information about managing users, see Managing users on Jazz Authorization Server.

    2. Select the type of user registry to use.
      • If you select an LDAP or SCIM user registry, you must provide information to configure the connection between the Jazz Team Server and your LDAP or SCIM provider. You might need to request the following information from your LDAP or SCIM administrator.

        For LDAP (including LDAP and LDAP/SDBM):

        • The LDAP registry location
        • User name and password to access the LDAP registry
        • Base user distinguished name
        • User property names mapping
        • Base group distinguished name
        • Jazz to LDAP group mapping
        • Group name property
        • Group member property

        For SCIM:

        • A URL of SCIM provider
        • User name and password to access the SCIM provider
        • Base user distinguished name
        • Base group distinguished name
        • Jazz groups to registry group mapping
      • If you select Non-LDAP External Registry, enter the same user ID that you used to log in to the setup wizard and provide an email address.
      • For WebSphere Application Server on z/OS with RACF security or WebSphere Application Server on IBM i with local OS authentication, select non-LDAP external registry.
    3. Optional: Disable the default ADMIN access by selecting the appropriate check box.
    4. Depending on the installed applications, under Engineering Requirements Management DOORS® Next, Engineering Workflow Management, and Engineering Test Management, select the Client Access Licenses (CALs) you want the administrative user to have. You can assign only one type of role-based CAL to the administrator. For example, you can assign the administrator only a Engineering Workflow Management - Developer CAL or a Engineering Workflow Management - Stakeholder CAL, but not both. The same rule applies to other applications.

      If you installed the trial licenses, you must accept the terms of a license before you can assign it to the administrative user. To activate a license, click Activate Trial; then, in the Client Access License Agreement window, click I accept the terms in the license agreement and click Finish.

      Tip: See Client access license management for information on how licenses can provide different levels of access to the capabilities in the applications in the current release.
    5. Click Next.
  10. On the Configure Data Warehouse page, provide information to set up a connection to the data warehouse. The data warehouse is a database that is used for reporting and analytics. By default, the application is configured to use the Derby database that is included with the application. If you have a database that is prepared on an enterprise database server such as Db2 or Oracle, you must configure the Jazz Team Server to use that database.
    1. Optional: To defer configuring the Data Warehouse, click I do not wish to configure the data warehouse at this time. If you do not configure the data warehouse, your applications will be functional but you will not store any reporting data and most reports will not work.
    2. In the Configure Data Warehouse Database Vendor and Connection Type section, select your Database Vendor and Connection type for that database vendor. The defaults are to use the included, pre-configured Derby database with a JDBC connection.
      You can either keep this default or choose a different database vendor and connection type.
      Note: If you select J2EE for connection type, you must also set the resultSetHoldability property to 1 in WebSphere Application Server. By default, this property is set to 2. If you do not set this property to 1, some of the data warehouse collection jobs might fail. For more information about resultSetHoldability, see your WebSphere Application Server documentation.
    3. If you are not using the Derby database, in the Configure Data Warehouse Database Connection Properties section, type the connection properties to connect to your database.
      The required values vary depending on your database vendor and connection type.
    4. For Db2, Oracle or Microsoft SQL Server, in the Database Table Space Folder field, type the path to an existing directory on the database server where the table space will be created and specify any additional advanced server properties for your database:
      • (Db2 and Oracle only) Temporary Table Space
      • ODS Table Space
      • ODS Index Table Space
      • Star Table Space
      • Star Index Table Space
      • Custom Report Database User
    5. If you used Rational® Common Reporting and you want to use the existing data warehouse database as the data warehouse for your ELM products, provide the information to connect to that existing database. You are prompted to add tables to your Rational Common Reporting or existing database.
    6. Click Test Connection to verify that the server can successfully communicate with the database by using the connection information that you provided.
    7. If you did not previously use a repotools command to create the database tables, you might see a warning that the database exists but that it does not contain any tables. To create the tables, click Create tables. You might have to wait several minutes for the command to finish.
      If you are using the default Derby data warehouse, you will not see this warning.
    8. Click Next.
  11. For each application, configure the database and the data warehouse similar to the steps you carried out previously.

    If you did not configure the data warehouse for the Jazz Team Server in step 10, on the Configure Data Warehouse page for the application, select I do not wish to configure the data warehouse at this time.

    For the user who runs the data collection jobs, you must enter a different user ID than the ID you are using to configure the application.

  12. On the Finalize Setup page for each application, click Finalize Application Setup. In this step, the consumer key and secret for an application are stored and the users on the Jazz Team Server are synchronized.
    Note: If the applications are on different servers and you see an error message that says 500 error - unexpected error occurred failure during finalize application step, verify that all servers have the correct times by using the NTP time server.
  13. On the Lifecycle Query Engine (/lqe) and Link Index Provider (/ldx) Configure Database pages, click Save JDBC Connection to save the database connection properties. On the Configure Backups page for these applications, you can enable a weekly backup that runs every Sunday at 2:00 AM. The schedule time can be changed through web UI after the setup is complete. You must also provide a path to an existing backup directory on the server. When done, click Save Configuration.
  14. On the Setup Report Builder page, click Connect to data sources. Jazz Team Server detects the data sources and makes the connection. If you want to import reports that are provided by your data sources, click Import ready-to-use reports.
  15. You might have to log on to any registered applications; log in as an administrative user (the same user ID you are using to run through the setup wizard). Then, click Finalize Application Setup. When the process is complete, click Next.
  16. On the Summary page, click Finish to access the Jazz Team Server Administration page where you can perform administration tasks such as managing the server, users, and licenses. For more information, see Administering IBM Engineering Lifecycle Management servers.