Installation and administration

Requirements

User permissions

The Remote Integration Agent connects to SD Elements using an API token. You can generate the token from a user who has a role with the following permissions:

  • Issue Tracker sync:

    • Manage > Global Roles > Integration > Edit Issue Tracker connections (enable)

  • Scanner import:

    • Manage > Global Roles > Integration > Edit verification connections (enable)

    • Manage > Project Roles > Integration > Sync with Issue Tracker tools (enable for each project requiring integrations)

    • Manage > Project Roles > Integration > Verify tasks (enable for each project requiring integrations)

  • LDAP Sync:

    • Access the SD Elements server as a user with superuser privileges.

Technical requirements

  • Network connectivity to port 443 (HTTPS) on the SD Elements server.

  • Network connectivity to port 443 (HTTPS) on the integration servers.

  • CentOS7/RHEL7 Linux, or Windows (Desktop/Server).

    • If using CentOS6/RHEL6, you may have to configure EPEL and IUS as additional repositories.

Configure a Remote Agent in SD Elements

Adding a Remote Integration Agent involves adding it to SD Elements, and installing the agent software.

Create a Remote Agent entry in SD Elements

Steps:
  1. From the gear icon settings menu, select Integration, then select the Remote Agents tab.

    67.5
  2. To add a new Remote Agent, click the plus add_circle button for a New Remote Agent.

    RIA integrations page.png
  3. Select the platform for the Remote Integration Agent, and choose between Windows and Linux.

    717
    1. The platform will be updated by the Remote Integration Agent when it runs.

    2. Choose the correct platform now to get the download link for the correct installer. Only the Windows installer is available for download directly from this screen.

  4. Enter a name for this Remote Agent. The name provides a descriptive label for the user and is not used during synchronizations.

  5. On a newly created Remote Agent, the Agent Version column will show Download and install agent.

    RIA agent list.png
    1. Click on this warning for download instructions.

Only one Remote Agent can be created. Synchronization using multiple remote agents is currently unsupported. After the Remote Integration Agent syncs successfully, this field will show the actual version number, or a warning if the Remote Integration Agent software needs an update. You can permanently delete a Remote Agent by clicking on the delete icon on the right side.

Create a system connector for an integration

Use the following steps to create a connector to a specific integrations service, such as an Issue Tracker, verification, or LDAP.

Steps:
  1. See Integrations for general instructions on creating connectors for specific services.

  2. When setting up a connector to use the Remote Integration Agent, select the option: This Issue Tracker server is hosted within a private network and cannot be reached directly by SD Elements.

  3. Create project connections, and set Sync Frequency to match the Remote Integration Agent’s scheduled syncs.

Manual integration is unavailable when a connector is marked as inaccessible.

SD Elements is ready, but no synchronization jobs will run until the Remote Installation Agent is installed. The next section explains the installation.

Install the Remote Integration Agent

The Remote Integration Agent supports Windows or Linux systems.

Windows

The installer is available directly from Integrations > Remote Agents in SD Elements once you have added a new remote agent.

The remote integration process runs periodically using the Windows Task Scheduler.

Prerequisites
  • The installation must be run by a user with Administrator permissions.

Steps:
  1. From the gear icon settings menu, select Integration, then select the Remote Agents tab.

  2. Click on the link on the Remote Agents page to download the installer.

  3. Run the installer and complete the installation using the wizard.

  4. Configure the integration:

    1. Click on the link on the Remote Agents page in SD Elements to download the installer.

    2. Run the downloaded executable and the installation wizard will start.

    3. If the Remote Integration Agent has been installed previously on this server, uncheck the box next to Generate Quickstart Configuration to use a previously created configuration.

    4. If this is the first time the Remote Integration Agent has been installed on this server, check the box next to Generate Quickstart Configuration to generate a new configuration. The installation wizard will guide you through the configuration.

      This configuration includes multiple prompts for the credentials required to create Windows Task Scheduler jobs for the supported time periods (Hourly, Daily, Weekly, and Monthly). These jobs manage the integrations over those time periods and are required fields.
  5. Once configured, the Remote Integration Agent installation will complete.

  6. Enter the user’s password when prompted.

Once the Remote Integration Agent is installed, the synchronization jobs will run as scheduled.

Edit the configuration

If you make a mistake during installation, you may still edit the configuration file manually. The configuration is in a text file called config.txt in the directory where the Remote Integration Agent was installed.

Test remote integration or run a manual integration

The installation of the Windows Task Scheduler jobs allows for integration to occur at the time periods configured in the project connectors in SD Elements. No further action is required for any scheduled integrations.

However, to synchronize projects manually or test remote integration after installation of the agent, use the following steps.

Steps:
  1. Have at least one project in SD Elements whose project connector is configured to run manually.

  2. Run the integrate.bat batch job.

    1. This is located in the directory where the Remote Integration Agent was installed.

Any issues or errors are reported in messages.log in the same directory.

Linux

The installer is available directly from Integrations > Remote Agents in SD Elements once you have added a new remote agent.

The Linux Remote Integration Agent is distributed as a set of wheel packages that are preferably installed in a Python Virtual Environment. This enables the Remote Integration Agent to be installed without modifying the system’s Python installation.

Where a version is indicated within angle brackets (<>), use your own version of the Remote Integration Agent or Python without the brackets.
Prerequisites:
  • The python-virtualenv package must be installed in order to create Python virtual environments.

Steps:
  1. Create a virtual environment for running the Remote Integration Agent:

    virtualenv ric-env
  2. Activate the virtual environment:

    source ric-env/bin/activate
  3. Extract the Remote Integration Agent package and ensure it is accessible to the user running the Remote Integration Agent. Next, enter the extracted directory:

    mkdir -p ./sdetools && tar -xzvf remote-integration-<11.0.7>.tar.gz -C ./sdetools && cd sdetools
  4. Get the Directory listing:

    pwd
    > /home/ricuser/sdetools
    ls
    > dist  sdetools-<11.0.7>-py2-none-any.whl  sdetools-<11.0.7>-py3-none-any.whl
    NOTE: Files exist for both Python 2 and Python 3. Select the version appropriate for your system: "sdetools-<11.0.7>-py2-none-any.whl" or "sdetools-<11.0.7>-py3-none-any.whl".
  5. Install the wheel package using pip:

    pip install --no-index --find-links=dist/ sdetools-<11.0.7>-py<3>-none-any.whl
  6. While the Virtual Environment is activated, you can call the sderic.py command_driver command:

    sderic.py help command_driver

Once the Remote Integration Agent is installed, you can call the sderic.py command_driver command to run a synchronization job while the Virtual Environment is activated.

You will need to provide a configuration file for the command to run. You can put this file in the default path ~/.sdetools.cnf. To specify a location for this file, use sderic.py command_driver -c <path-to-your-config>. Here is a sample configuration file.
[global]
# APIv2 connection string
sde_api_token=<token>@<sdelements.instance.com>

# Remote Integration Agent ID
ria_id=<ria id>

# Debug options
#    log_level: default, verbose, debug, error, quiet
#    debugmods: module name
log_level=default
#debugmods=sdetools.sdelib.restclient

# Add additional options to the commands
sde_validate_cert=True
command_params={"issue_tracker_validate_cert":"True", "analysis_validate_cert":"True", "ldap_validate_cert":"True"}

Schedule ongoing integration

Windows
  1. The Remote Integration Agent relies on the Windows Task Scheduler for scheduled integration runs. During installation, the installer will prompt a user to automatically create Windows Task Scheduler entries for hourly, daily, weekly, or monthly frequencies.

Linux
  1. By using the filtering options outlined above, it is possible to schedule ongoing integration to match the SD Elements user interface.

  2. On Unix-like environments, the following crontab can be used to run jobs consistent with the UI. In the terminal type:

    crontab -e
  3. Then paste the following crontab:

    # Hourly (On the hour)
    0 * * * * [virtualenv path]/bin/python [virtualenv path]/bin/sderic.py command_driver --sde_api_token=APIv2_CONNECTION_STRING --filter_frequency=hourly > /path/to/output.log 2> /path/to/debug.log
    # Daily (1230)
    30 0 * * * [virtualenv path]/bin/python [virtualenv path]/bin/sderic.py command_driver --sde_api_token=APIv2_CONNECTION_STRING --filter_frequency=daily > /path/to/output.log 2> /path/to/debug.log
    # Weekly (Mondays at 0130)
    30 1 * * 1 [virtualenv path]/bin/python [virtualenv path]/bin/sderic.py command_driver --sde_api_token=APIv2_CONNECTION_STRING --filter_frequency=weekly > /path/to/output.log 2> /path/to/debug.log
    # Monthly (First of the month at 0230)
    30 2 1 * * [virtualenv path]/bin/python [virtualenv path]/bin/sderic.py command_driver --sde_api_token=APIv2_CONNECTION_STRING --filter_frequency=monthly > /path/to/output.log 2> /path/to/debug.log
  4. Update the paths to reflect the relevant locations.

results matching ""

    No results matching ""