Skip to content

Deployment guide

Jump to bottom
Yogesh edited this page Jun 7, 2021 · 3 revisions

Prerequisites

To begin, you will need:

There are two ways to deploy Checklist App. You can choose one of the following ways -

  1. NPM based deployment
  2. PowerShell based deployment

NPM based Deployment Steps

Prerequisites

Step 1: Create your Checklist app

To create the Teams Checklist app package:

  1. Make sure you have cloned or downloaded and unzipped, the app repository locally.
  2. Open the actionManifest.json file in a text editor.
  3. Change the placeholder fields in the manifest to values appropriate for your organization.
    • packageID - A unique identifier for this app in reverse domain notation. E.g: com.contoso.checklistapp. (Max length: 64)
    • developer.name (What's this?)
    • developer.websiteUrl
    • developer.privacyUrl
    • developer.termsOfUseUrl

Note: Make sure you do not change to file structure of the app package, with no new nested folders.

Step 2: Deploy app to your organisation

  1. Install Node.js (using https://nodejs.org/en/download/) locally on your machine.

  2. Open Command Line on your machine.

  3. Navigate to the app package folder with the name microsoft-teams-checklist-app.

  4. Run the following command to download all the dependent files mentioned in package.json file of the app package.

    npm install

  5. Once the dependent files are downloaded, run the below command to deploy the app package to your Microsoft 365 subscription. When prompted, log in to your AAD account.

    npm run deploy

  6. An AAD custom app, Bot are programmatically created in your tenant to power the Checklist message extension app in Teams.

  7. Once run, a Checklist Teams app zip file is generated under output folder in the same directory as your cloned app repository locally with the name microsoft-teams-checklist-upload.zip.

Step 3: Run the app in Microsoft Teams

If your tenant has sideloading apps enabled, you can install your app by following the instructions here.

You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install. See here.

Upload the generated Checklist Teams app zip file (the microsoft-teams-checklist-upload.zip) under output folder in the same directory as your cloned app repository locally to your channel, chat, or tenant’s app catalog.

Step 4: Update your Checklist Teams app

If you want to update the existing Checklist Teams app with latest functionality -

  1. Make sure you have cloned the latest app repository locally.

  2. Open the  actionManifest.json file in a text editor.

    • Change the placeholder fields (packageID, developer.name, developer.websiteUrl, developer.privacyUrl, developer.termsOfUseUrl) in the manifest with existing values in your Checklist Teams app.
    • Update the version field in the manifest. Make sure latest version number is higher than previous version number.

  3. Run the below command to update your Checklist Teams app with the latest bits of code. When prompted, log in using your AAD account.

    npm run update-teams-app

  4. Your Checklist app on Teams automatically gets updated to the latest version.

PowerShell based Deployment Steps

Step 1: Create your Checklist app

To create the Teams Checklist app package:

  1. Clone this app repository using command git clone https://github.com/OfficeDev/microsoft-teams-app-checklist.git or you can download and unzip it.

  2. Open the app repository folder and go to the folder named bundle.

  3. Open the actionManifest.json file in a text editor. You will find a couple of placeholder fields there which you need to update to values appropriate for your organization. Please note that all the URLs should begin with https://.

    • packageID - A unique identifier for this app in reverse domain notation. E.g: com.contoso.checklistapp. (Max length: 64)
    • developer.name (What's this?) - E.g: contoso
    • developer.websiteUrl - (E.g: https://<organization-url>)
    • developer.privacyUrl - (E.g: https://<organization-privacy-url>)
    • developer.termsOfUseUrl - (E.g: https://<organization-termsOfUse-url>)

  4. Navigate into the bundle folder. Select all the content inside the folder and create a ZIP file named MSTeamsApp.zip.

Note: Make sure you do not change to file structure of the bundle folder, with no new nested folders.

Step 2: Deploy app to your organisation

  1. Open a Windows PowerShell console on your machine, to run PowerShell commands mentioned in subsequent steps. Following table help you to find PowerShell in your machine.

    OS Version Location / Help Link
    Windows 10 Click left lower corner Windows icon, start typing PowerShell
    Windows 8, 7 and other versions Help Link
    Linux Help Link
    Mac Help Link

  2. Navigate to folder named script located in the cloned/downloaded repository using cd command.

    cd <cloned/downloaded local repository path>\script

  3. If you have downloaded the app repository (not cloned), then run following PowerShell command to allow PowerShell script execution.

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force -Scope CurrentUser

  4. Run the following command to import necessary module needed for deployment.

    import-module .\ActionPackageDeploy.psm1

  5. Run following PowerShell command to deploy the app package to your Microsoft 365 subscription. MSTeamsApp.zip created in Step 1 is used in this command.

    New-ActionPackage -PackageZipFilePath .\..\bundle\MSTeamsApp.zip

    An AAD custom app, Bot are programmatically created in your tenant to power the Checklist message extension app in Teams.

  6. After successful execution of above command, You can find the downloaded Teams app at the path printed on your console.

Step 3: Run the app in Microsoft Teams

If your tenant has sideloading apps enabled, you can install your app by following the instructions here.

You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install. See here.

Upload the generated Checklist Teams app zip file (the microsoft-teams-appzip-upload.zip generated in above step) to your channel, chat, or tenant’s app catalog.

Updating your Checklist Teams app

To update existing Checklist Teams app package -

  1. Make sure you have clone or download the latest app repository locally.

  2. Open the app repository folder and go to the folder named bundle.

  3. Open the actionManifest.json file in a text editor.

    • Ensure that the placeholder fields match the existing values, otherwise the app will not get updated. To do this, open the manifest file and change fields (packageID, developer.name, developer.websiteUrl, developer.privacyUrl, developer.termsOfUseUrl) to existing values.
    • Update the version field in the manifest. Make sure latest version number is higher than previous version number. (E.g. If previous version is 1.0.0 then newer version can be 1.0.1 or 1.1.0).

  4. Zip all the content in the folder named bundle and name the zip file as MSTeamsApp.zip.

  5. Perform following steps to update your Checklist Teams app with the latest bits of code.

    • Navigate to script folder

      cd <cloned/downloaded repository path>\script

    • Run command to import necessary modules to current PowerShell session

      import-module .\ActionPackageDeploy.psm1

    • Run update command

      Update-ActionPackage -PackageZipFilePath .\..\bundle\MSTeamsApp.zip

  6. On success, your Checklist app will automatically get updated to the latest version.

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally