diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/docs/.order b/docs/.order new file mode 100644 index 00000000..105fd74d --- /dev/null +++ b/docs/.order @@ -0,0 +1,3 @@ +About-Azure-DevOps-Demo-Generator +Features-Timeline +Azure-DevOps-Demo-Generator-REST-API-Reference \ No newline at end of file diff --git a/docs/About-Azure-DevOps-Demo-Generator/.order b/docs/About-Azure-DevOps-Demo-Generator/.order new file mode 100644 index 00000000..e1d6e413 --- /dev/null +++ b/docs/About-Azure-DevOps-Demo-Generator/.order @@ -0,0 +1,3 @@ +Known-Issues-and-FAQ +Using-the-Generator +Build-your-own-template \ No newline at end of file diff --git a/docs/About-Azure-DevOps-Demo-Generator/Build-your-own-template.md b/docs/About-Azure-DevOps-Demo-Generator/Build-your-own-template.md new file mode 100644 index 00000000..d97c63ce --- /dev/null +++ b/docs/About-Azure-DevOps-Demo-Generator/Build-your-own-template.md @@ -0,0 +1,57 @@ +# Using the Extractor +--------- + +Azure DevOps Generator provides a number of templates, out of the box, that supports a wide variety of scenarios, from different project types to different programming languages, deployment platforms, etc., In addition to this, the generator also allows users to make their own templates. Users can convert their existing projects into templates and then provision new projects using that template. The ability to have custom templates can be useful in many scenarios, such as building custom training materials, provision only certain artifacts, etc., + +This document walks you through the steps on how you can use the extractor. + +## Before you start + +Setup an Azure DevOps project and make sure it is ready to be extracted. The extractor will capture the contents of the project and save them as JSON files which will be archived into a zip file. + +## Building a new custom template + +1. Access the generator with the query parameter **"enableextractor=true"** added to the URL: [https://azuredevopsdemogenerator.azurewebsites.net/?enableextractor=true](https://azuredevopsdemogenerator.azurewebsites.net/?enableextractor=true) + + ![Azure DevOps Generator Home Page](images/homepage.png) + +1. After you sign in, on the main page, you will see a new link labelled **"Build your own template"** + + ![Build your template link on main page](images/buildyourtemplatelink.png) + +1. Selecting that will open the **extractor** main page in a new tab. + + ![Extractor Home Page](images/extractorhomepage.png) + +1. Select the organization and then the project that you want to turn into a template. + +1. Click **Analyze**. This will validate if the project is one of the supported types (only Agile and Scrum based projects are supported for the time-being) and that all of the contents can be read.At the end of the analysis, you will see the artifacts and count of items for you to confirm if the extractor has read all items correctly. + + ![Analyzing the project](images/analyze.png) + +1. If it is correct and you wish to proceed, select the **Generate** button. This will again read all the items from the project but this time, the contents will be saved as JSON data. After all the items have been extracted, the folder will be archived into a zip file. + +1. Select the link to download the zip file. Note that the zip file is not stored on the server side - so, make sure you download the file. It will not be available after you close the page. + + ![Downloadin the generated template](images/generatedfile.png) + +**Note:** The Extractor does not support all item types and so it should not be considered as a migration tool for moving projects from one server to another. For what's supported and what's not supported, see the [limitations]() section + +## Provisioning your project from your custom template + +1. Return back to the generator page or re-open it again if you have already closed it. You should use the **enableextractor=true** query parameter in the URL. + +1. Select **Choose Template** + +1. You will see a new tab labelled **Private**. Select the tab. + +1. Select **Browse** and select the zip file you downloaded zip file. + +1. Click **OK** to close the dialog. Choose **Create Project** to start provisioning a project + + + +------------- + +Previous: [Using the Generator](/About-Azure-DevOps-Demo-Generator/Using-the-Generator) + diff --git a/docs/About-Azure-DevOps-Demo-Generator/Known-Issues-and-FAQ.md b/docs/About-Azure-DevOps-Demo-Generator/Known-Issues-and-FAQ.md new file mode 100644 index 00000000..fd9781d9 --- /dev/null +++ b/docs/About-Azure-DevOps-Demo-Generator/Known-Issues-and-FAQ.md @@ -0,0 +1,26 @@ +[[_TOC_]] + + +# Known Issues: + +## **Issue:** Error while creating release definition: +Tasks with versions 'ARM Outputs:4.*' are not valid for deploy job 'Agent job' in stage Stage 1 + +**Cause:** This is usually caused by one of the third-party extensions not enabled or installed in your Azure DevOps org. Usually installation of extensions are quick but sometimes, it can take a few minutes (or even hours!) for an extension to be available to use, after it is installed in the marketplace. + +**Workaround:** You can try waiting for a few minutes and confirm whether the extension is available to use, and then run the generator again. + +------------------ +# Frequently Asked Questions + +## Q: Is the Generator open-source? Can I get access to the code? + +Azure DevOps Generator is not open-sourced yet. While we plan to make this open source, it is being evaluated by the product and legal teams + +--------------- + +## Q: How can I build my own template? + +Yes, you can take a snapshot of your project and turn into a template and use it for provisioning future projects using the **Extractor** - See [Build-your-own-template](/About-Azure-DevOps-Demo-Generator/Build-your-own-template) + +----------- \ No newline at end of file diff --git a/docs/About-Azure-DevOps-Demo-Generator/Using-the-Generator.md b/docs/About-Azure-DevOps-Demo-Generator/Using-the-Generator.md new file mode 100644 index 00000000..d1dcfd96 --- /dev/null +++ b/docs/About-Azure-DevOps-Demo-Generator/Using-the-Generator.md @@ -0,0 +1,53 @@ + +# Using the Azure DevOps Demo Generator +------ + + +1. Browse to the [Azure DevOps Demo Generator site](https://azuredevopsdemogenerator.azurewebsites.net/) by click the link, or copy `https://azuredevopsdemogenerator.azurewebsites.net/` into your browser's URL field. + +2. Click **Sign In** and provide the Microsoft or Azure AD account credentials associated with an organization in Azure DevOps Services. If you don't have an organization, click on **Get Started for Free** to create one and then log in with your credentials. + + +![Image of VSTS Demo Generator V2 login](/About-Azure-DevOps-Demo-Generator/images/homepage.png) + + +1. After you sign in, select **Accept** to grant the Demo Generator permissions to access your Azure DevOps account. + + +1. Select the organization you will use to host the project created by the Azure DevOps Demo Generator. (You may have multiple accounts of which you are a member, and which are associated with your login, so choose carefully.) Provide a name for your project (such as "MyProjectDemo" ) that you and other contributors can use to identify it as a demo project. + +![Image of the generator main page](/About-Azure-DevOps-Demo-Generator/images/mainpage.png) + + +Lastly, select the demo project template you want to provision by clicking **...** (Browse) button. + +![Image of VSTS Demo Generator template selection screen](/About-Azure-DevOps-Demo-Generator/images/templateselection.png) + + + >The default template is **SmartHotel360**, which contains complete ASP.NET 2 web mobile and desktop business apps for a hotel, and can be deployed using Docker containers. Other templates include **MyHealthClinic**, which defines a team project for an ASP.NET Core app that deploys to Azure App Service; **PartsUnlimited**, which defines an ASP.NET app with customized CI/CD pipelines; and **MyShuttle**, which defines a Java app and Azure App service deployment. + + >All four templates provide fictional Azure DevOps users and pre-populated Agile planning and tracking work items and data, along with source code in an Azure Repos Git repo, as well as access to Azure Pipelines. + +1. Some templates may require additional extensions to be installed to your organization. The demo generation process checks to see if these extensions are already installed. If the extension is already installed, a green check will be displayed in front of the extension name. If the extension is **not** installed, select the empty check boxes to install the extension(s) to your account. When ready, click on **Create Project** button. + + > If you want to manually install the extensions, click on the provided link for a specific extension, which takes you to the extension's page on Azure DevOps Marketplace. From there, you can install the extension. + +2. Your project may take a couple of minutes for the Demo Generator to provision. When it completes, you will be provided with a link to the demo project. + + +![Image of Azure DevOps Demo Generator project created screen](_img/projectcreated.png) + +1. Select the link to go to the new demo Azure DevOps Services project and confirm it was successfully provisioned. + + +![Image of Azure DevOps Demo Generator provision confirmation screen](_img/projecthomepage.png) + + +> You must provide your own information such as URLs, logins, password, and others for the configuration of demo endpoints that use Azure resources. + +------------- + + + + +Next: [Building your own template](/About-Azure-DevOps-Demo-Generator/Build-your-own-template) \ No newline at end of file diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/analyze.png b/docs/About-Azure-DevOps-Demo-Generator/images/analyze.png new file mode 100644 index 00000000..5752bf0d Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/analyze.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/buildyourtemplatelink.png b/docs/About-Azure-DevOps-Demo-Generator/images/buildyourtemplatelink.png new file mode 100644 index 00000000..7183abfa Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/buildyourtemplatelink.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/extractorhomepage.png b/docs/About-Azure-DevOps-Demo-Generator/images/extractorhomepage.png new file mode 100644 index 00000000..4c410462 Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/extractorhomepage.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/generatedfile.png b/docs/About-Azure-DevOps-Demo-Generator/images/generatedfile.png new file mode 100644 index 00000000..31c57a49 Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/generatedfile.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/homepage.png b/docs/About-Azure-DevOps-Demo-Generator/images/homepage.png new file mode 100644 index 00000000..6d30ca39 Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/homepage.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/mainpage.png b/docs/About-Azure-DevOps-Demo-Generator/images/mainpage.png new file mode 100644 index 00000000..67758c5b Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/mainpage.png differ diff --git a/docs/About-Azure-DevOps-Demo-Generator/images/templateselection.png b/docs/About-Azure-DevOps-Demo-Generator/images/templateselection.png new file mode 100644 index 00000000..93de6481 Binary files /dev/null and b/docs/About-Azure-DevOps-Demo-Generator/images/templateselection.png differ diff --git a/docs/Azure-DevOps-Demo-Generator-REST-API-Reference.md b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference.md new file mode 100644 index 00000000..8c79d70f --- /dev/null +++ b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference.md @@ -0,0 +1,66 @@ +# Welcome to the Azure DevOps Services REST API Reference +------------------------- +We have added API support to the Azure DevOps Demo Generator so that it can be invoked externally. This page has all the instructions that you need to know how to call the API. + +* Calling the API from a [PowerShell Script](/Azure-DevOps-Demo-Generator-REST-API-Reference/Azure-DevOps-REST-API-%2D-Call-API-with-powershell) + + +## Create a Project + + `POST https://azuredevopsdemogenerator.azurewebsites.net/api/environment/create` + +## Sample Request Body + +``` +{ + "accessToken": "********************************", + "organizationName": "DemoProjects", + "templateName": "contososhuttle2", + "users": [ + { + "email": "abc@outlook.com", + "ProjectName": "TestProject1" + }, + { + "email": "abc@outlook.com", + "ProjectName": "TestProject2" + } + ] +} +``` +### Parameters + + + + + + + + + + + + + + +
ParameterDescription
accessTokenPAT for the Azure DevOps Org. Note that the projects will be created under the user name in which the PAT is created. The PAT should be created with the following scopes +
  • read, write and manage projects and teams and
    • +
  • read and write permissions for Work Item, Code, Build, Wiki, Dashboard, Extensions, etc.,
    • Organization name Name of the Azure DevOps org in which the project will be created +
    templatNameThe short name of the template
    usersUsers information. You can specify any number of users.
  • Email address of the user
    • Name of the project
    + +## Sample Response + + + +## Validation Messages + + + + + + + +
    Validation for account based on provided Organisation nameIf Organisation Name is empty, then message will be "Provide a valid Account name" with status code 402 Bad Request
    Validation for access tokenIf access token is empty, then message will be "Token of type Basic must be provided" with status code 402 Bad Request
    Validation for Project NameIf the Project Name is invalid, then message will be "Invalid Project name" with status code 402 Bad Request +If the Project Name is same as reserved keywords, then message will be "Project name must not be a system-reserved name such as PRN, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM10, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL, CON, AUX, SERVER, SignalR, DefaultCollection, or Web" with status code 402 Bad request
    Check for Duplicate Project Name in Request bodyIf the Project Name duplicate in the request body, then message will be "ProjectName must be unique" with status code 402 Bad Request
    Validation for TemplateNameIf templateName is empty, then message will be +"Template Name should not be empty" with status code 402 Bad Request. +If the given template name not found in the source, then message will be "Template Not Found!" with status code 402 Bad Request
    Validation for Email ID and Project Name"EmailId or ProjectName is not found" with status code 402 Bad Request
    \ No newline at end of file diff --git a/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/.order b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/.order new file mode 100644 index 00000000..c8bd545c --- /dev/null +++ b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/.order @@ -0,0 +1,2 @@ +Get-status-of-project-creation-using-TrackId +Azure-DevOps-REST-API-%2D-Call-API-with-powershell \ No newline at end of file diff --git a/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Azure-DevOps-REST-API-%2D-Call-API-with-powershell.md b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Azure-DevOps-REST-API-%2D-Call-API-with-powershell.md new file mode 100644 index 00000000..27dabb69 --- /dev/null +++ b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Azure-DevOps-REST-API-%2D-Call-API-with-powershell.md @@ -0,0 +1,59 @@ +## Here is the details on how to call an API to create project using powershell + +``` +$pat = "_PAT_" +$encodedPat = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(":$pat")) + +$body = @" +{ + "accessToken": "_PAT_", + "organizationName": "_ORG_", + "templateName": "_TEMPLATENAME_", + "users": [{ + "email": "_EMAIL_", + "ProjectName": "_PROJECTNAME_" + }] +} +"@ + +Write-Host "Provisioning project ..." -ForegroundColor Blue -BackgroundColor Cyan +$resp = Invoke-WebRequest -Uri "https://demogenapi.azurewebsites.net/api/environment/create" -Method "POST" -ContentType application/json -Body $body + +$returnCode = $resp.StatusCode +$returnStatus = $resp.StatusDescription + +if ($returnCode -ne "202") { + Write-Host "Create project failed - $returnCode $returnStatus" -ForegroundColor White -BackgroundColor Red + break +} +Write-Host "Project queued ... awaiting completion ..." -ForegroundColor Blue -BackgroundColor Cyan + +$method = "GET" +$listurl = "https://dev.azure.com/culater/_apis/projects?api-version=5.1-preview.4" +$resp = Invoke-RestMethod -Uri $listurl -Method $method -Headers @{Authorization = "Basic $encodedPat"} + +#Wait till project is finished deploying +while (1 -eq 1) +{ + $resp = Invoke-RestMethod -Uri $listurl -Method $method -Headers @{Authorization = "Basic $encodedPat"} + + foreach ($project in $resp.value) + { + $projname = $project.name + $projStatus = $project.state + #Write-Host "Inspecting project $projname - $projStatus" -ForegroundColor Blue -BackgroundColor Cyan + if ($projname -eq "davesvab-ContosoShuttle1" -and $projStatus -eq "wellFormed") + { + break + } + Start-Sleep -seconds 1 + } + + if ($projname -eq "davesvab-ContosoShuttle1" -and $projStatus -eq "wellFormed") + { + break + } +} +Write-Host "Project provisioned successfully" -ForegroundColor Blue -BackgroundColor Cyan + +``` diff --git a/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Get-status-of-project-creation-using-TrackId.md b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Get-status-of-project-creation-using-TrackId.md new file mode 100644 index 00000000..36fb667c --- /dev/null +++ b/docs/Azure-DevOps-Demo-Generator-REST-API-Reference/Get-status-of-project-creation-using-TrackId.md @@ -0,0 +1,27 @@ +**Here is the details about how to track the project creation status using TrackId** + +## Track project create status + + `GET https://azuredevopsdemogenerator.azurewebsites.net/api/environment/currentprogress?id={TrackId}` + +### Parameters + + + + + + + + + +
    ParameterDescription
    idid is TrackId value
    + +## Sample Response +``` +"Project {ProjectName} created" +. +. +. +. +"Successfully Created" +``` diff --git a/docs/Features-Timeline.md b/docs/Features-Timeline.md new file mode 100644 index 00000000..326cb640 --- /dev/null +++ b/docs/Features-Timeline.md @@ -0,0 +1,3 @@ +# Azure DevOps Demo Generator Features Timeline + +Feature list is a peek into our roadmap. It identifies some of the significant features we are currently working on and a rough timeframe for when you can expect to see them. It is not comprehensive but is intended to provide some visibility into key investments. Each feature is linked to the public roadmap project where you can learn more about a particular item \ No newline at end of file diff --git a/docs/Features-Timeline/.order b/docs/Features-Timeline/.order new file mode 100644 index 00000000..9cfa06cd --- /dev/null +++ b/docs/Features-Timeline/.order @@ -0,0 +1,2 @@ +YAML-Pipeline-Support +Dashboard-creation \ No newline at end of file diff --git a/docs/Features-Timeline/Dashboard-creation.md b/docs/Features-Timeline/Dashboard-creation.md new file mode 100644 index 00000000..69c0312f --- /dev/null +++ b/docs/Features-Timeline/Dashboard-creation.md @@ -0,0 +1,9 @@ +# Export and Create Dashboard +Export the dashboard using template builder with valid placeholders +when importing/creating the dashboard, replace the placeholders with valid Ids + +## Observations +- Dashboard contains different types of widgets +- Widgets can be segregated based on widget `typeId` +- Widgets can contain `QueryId`,`BuildId`,`ReleaseId`,`GroupKey`,`RepositoryId` etc +- Not all the Ids can be replace with placeholders, only query Ids can be replaced. Since other widgets might have different names than the `Build Name`,`Release Name`, `Repo Name` \ No newline at end of file diff --git a/docs/Features-Timeline/YAML-Pipeline-Support.md b/docs/Features-Timeline/YAML-Pipeline-Support.md new file mode 100644 index 00000000..af420992 --- /dev/null +++ b/docs/Features-Timeline/YAML-Pipeline-Support.md @@ -0,0 +1,8 @@ +# Support for YAML pipeline +Sprint#32 May 6, 2019 + +------------------------------ + +In this sprint we are adding YAML pipelines to the generator. Templates can now have CI and CD definitions defined in YAML and those pipelines will be provisioned when creating a new instance through the generator. We are also adding to the extractor so users can extract projects that has pipelines defined in YAML. + +For more information on YAML pipelines in Azure Pipelines, see [https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema) \ No newline at end of file