Skip to content
Lynxwork

Lynxwork Azure DevOps OSLC Server - Installation and Usage Guide

The LynxWork Azure DevOps OSLC Server is provided as a standard Web Application Archive (.war) file. It can be deployed in any compatible servlet container, such as Apache Tomcat or Eclipse Jetty. It can also be packaged and executed within a Docker container, or using Azure Web Apps.

This guide describes how to deploy the application:

  • In a Docker container
  • In an Apache Tomcat environment
  • As an Azure Web App (App Service)

The software distribution includes the following files:

File Purpose
azuredevops.war The deployable web application archive
lynxwork.lic The required license file
tomcat-context-template.xml Apache Tomcat deployment
docker-compose-template.yml and Dockerfile Docker-based deployment
deploy.ps1 and main.bicep Azure Web App

Preparations

Before starting, make sure you have:

Azure DevOps Cloud

For Azure DevOps Cloud:

  • {my_organisation} — The name of the organistion that is visible in the Azure DevOps site URL, such as https://dev.azure.com/{my_organisation}
  • Register an application and configure its permissions as instructed under Build Azure DevOps integrations with Microsoft Entra OAuth apps
    • Set a Redirect URI to {connector_base_url}/oslc/oauth2/callback
    • Add 2 API permissions: vso.work_write and vso.extension.data
    • Add a Client Secret and keep a record of it.
    • Make a record of the following:
      • {client_id}
      • {client_secret}
      • {tenant_id}

Azure DevOps Server

For Azure DevOps Server (Ensure the HTTPS protocol is used with a trusted certificate.)

  • {azure_devops_server_api_base_url} — The URL for the Azure DevOps REST APIs. Typically, it takes the form https://azure.my-organisation.com/DefaultCollection (but can be any collection)
  • {azure_devops_personal_access_token} — obtain a Personal Access Token as instructed under Use Personal Access Token, with the following scopes:
    • Work Items: Read & Write
    • Extension Data: Read & Write (May need to select Show all scopes)

Deploy within a Docker container

  1. Install Docker Engine from the Docker website.
  2. Create a deployment directory of your choice (e.g. /opt/azuredevopsconnector on Linux, or C:\azuredevopsconnector on Windows) and copy the provided files into it:
    • azuredevops.war
    • Dockerfile
    • docker-compose-template.yml
  3. Rename docker-compose-template.yml to docker-compose.yml in that deployment directory.
  4. Copy the license file into a suitable location. For example, copy it alongside docker-compose.yml making the setup self-contained. Update the corresponding volume mapping in docker-compose.yml: /opt/azuredevopsconnector/lynxwork.lic:/var/lib/jetty/lynxwork.lic
  5. Create an oauth subfolder in a suitable location. For example, alongside docker-compose.yml. Update the corresponding volume mapping in docker-compose.yml: /opt/azuredevopsconnector/oauth:/var/lib/jetty/oauth
  6. Edit docker-compose.yml and replace all remaining values enclosed in {} with the appropriate configuration values for your environment.
  7. Run the Connector from the deployment directory: docker compose up -d
  8. Access the application at {connector_base_url}.

Deploy in Apache Tomcat

  1. Install Java 21 JDK from Adoptium.
  2. Install Tomcat 10 from the Apache Tomcat website. We refer to the Tomcat installation directory as .
  3. Copy the azuredevops.war file to Tomcat’s webapps directory, typically located at /webapps/
  4. Copy the provided lynxwork.lic license file to TOMCAT_HOME/lynxwork.lic.
  5. Create an oauth folder at TOMCAT_HOME/oauth/. Ensure Tomcat has write permissions to this folder.
  6. Copy and rename the provided tomcat-context-template.xml to /conf/Catalina/localhost/azuredevops.xml
  7. Edit the copied context file and replace all values enclosed in {} with the appropriate configuration values for your environment.
  8. Restart Tomcat.
  9. Access the application at {connector_base_url}

Deploy in Azure Web App

  1. Install Azure CLI (az)

  2. Install PowerShell Core (pwsh 7+ )

  3. Use the provided scripts to deploy the Connector:

    Terminal window
    pwsh ./deploy.ps1 `
      -ResourceGroup "YOUR_AZURE_RESOURCE_GROUP_NAME" `
      -WebAppName "YOUR_AZURE_WEBAP_NAME" `
      -Location "YOUR_AZURE_WEBAP_LOCATION" `
      -WarPath "PATH_TO_WAR_ARTIFACT_FILE" `
      -AzureDevOpsOrganization "{my_organisation}" `
      -OAuth2TenantId "{tenant_id}" `
      -OAuth2ClientId "{client_id}" `
      -OAuth2ClientSecret "{client_secret}"

  4. Copy the provided lynxwork.lic license file to /home/azure-devops-connector/lynxwork.lic (or any desired path, as long as it corresponds to the environment variable LYNXWORK_LICENSE_FILE)

  5. Create an oauth folder at /home/azure-devops-connector/oauth/ (or any desired path, as long as it corresponds to the folder of the environment variable LYNXWORK_OAUTH1_STORE_FILE). Ensure Tomcat has write permissions to this folder.

Configuring Consumer Applications

The Azure DevOps OSLC Server implements the OSLC standard. Connecting to the server from an engineering application is typically done following OSLC’s discovery capabilities. Consult the manual of the consumer application for further configuration details.

Usage Guide

To create traceability links to Azure DevOps items, consult your consumer application’s manual for details.