Action-package-deploy NPM

Action Package Deployment Scripts

This package contains the scripts for deploying action packages to ActionPlatform

Installation

To install the stable version:

npm

npm install action-package-deploy --save-dev

yarn

yarn add action-package-deploy --dev

Usage

To upload an action package

upload-action-package -z <PackageZipPath> [-t <TeamsAppDownloadDirectory>]

To create Teams app from an action package

create-teams-app -p <PackageId> -d <DownloadDirectory>

To create Teams app from an action package and existing AAD App

create-teams-app -p <PackageId> -d <DownloadDirectory> --aa <AadAppId>

To delete an action package

delete-action-package -p <PackageId>

To get an action package

get-action-package -p <PackageId>

To get action packages in a tenant

get-action-packages [-c <CreatorIdFilter>] [-n <PackageNameFilter>]

Dev Inner-Loop Scripts

Beside package deployment a developer may need to verify changes to an action package quickly - without deploying the bits again and again. For this, the developer can start an inner-loop against an action package from a local directory containing all its views/contents - in that case, all the package resources will be served from that local directory directly instead of service. Only a developer can see the package content from inner-loop directory.

Usage

To create inner-loop for an action package

create-inner-loop -p <PackageId> -d <InnerLoopDirectory> [-x <InnerLoopExpiryInHours>]

To get inner-loop status of an action package

get-inner-loop -p <PackageId>

To delete inner-loop status of an action package

delete-inner-loop -p <PackageId>

Inner-loop expiry

Inner-loop can be set for a maximum duration of 4hrs. After that the inner-loop window will automatically close and it needs to be re-created again.

Inner-loop with watch mode

Inner-loop works best if you set watch mode in your build scripts - it will incrementally build your package whenever a change is detected. Below is an example of a package.json where watch mode is enabled using webpack coupled with an inner-loop script.

{
    ...
    "scripts": {
        ...
        "start": "webpack --watch --mode=development --output-path=dist/output",
        "inner-loop": "create-inner-loop -d dist/output/ -p com.contoso.PackageId",
        ...
    },
    ...
}

Now in two separate terminals you can run below commands

Start building your package in watch mode

npm run start

Start the inner-loop

npm run inner-loop

Transform Kaizala Packages

Using the below script one can transform a Kaizala package and import it to ActionPlatform (and Teams in turn).

transform-kaizala-package -k <KaizalaPackageZipPath> -a <ActionPackageDownloadPath> [-t <TeamsAppDownloadPath>] [-p <ParameterJsonPath>] [--dn <DeveloperName> --dw <DeveloperWebsiteUrl> --dp <DeveloperPrivacyUrl> --dt <DeveloperTermsUrl>]

The additional parameters which are absent in a Kaizala package can be feed to the command using a json file like below.

{
    ...
    "developer": {
        "name": "Contoso",
        "websiteUrl": "https://www.contoso.com",
        "privacyUrl": "https://www.contoso.com/privacy",
        "termsOfUseUrl": "https://www.contoso.com/terms"
    },
    ...
}

Debugging Scripts

With each command one can set the console logging levels too. By default the log level is set to info

status - Just success/failure logs will be shown
info - Beside status messages, informative logs will be shown
debug - More debug logs will be shown
none - No logs will be shown

To set log level use -l or --log-level switch like below

upload-action-package -z <PackageZipPath> -l debug

Additionally, all the debug logs are dumped into user's home directory inside action_package_deploy_logs/<DD_MM_YYYY>.log file

Manually Creating AAD Apps

All Teams message extension Actions require a backing AAD App to function properly. The AAD App is automatically created as part of the Action deployment using the caller's credentials. However, if you prefer to create the AAD App yourself, you can do so and pass the AAD App ID to us.

The AAD App should have the following properties:

Sign-in audience is Multi-Tenant.
Add Actions Platform Service Principal as co-owner (App ID: 06dd8193-75af-46d0-84bb-9b9bcaa89e8b).
- You need to find out the SP ID for your tenant to add it as co-owner.
- To figure out the SP ID use the following GET API in the Graph Explorer portal: https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '06dd8193-75af-46d0-84bb-9b9bcaa89e8b'
- You can add the SP via Graph Explorer portal using the Add Owner API.

Alternatively, you can create the AAD App using the helper script CreateAadApp.ps1. This tries to install the AzureAD PS1 module to create the AAD App. If its installation fails you need to fall back to manual steps described above:

CreateAadApp -DisplayName <name>

And pass the AAD App ID as part of the deployment:

create-teams-app -p <PackageId> -d <DownloadDirectory> --aa <AadAppId>

Error while creating AAD App

If you get the following error while creating the AAD App:

Actions Platform SP is not provisioned in the tenant.

Run the following commands to provision the Actions Platform SP in the tenant. When prompted, log in using your AAD account.

import-module "<AbsolutePathFor_ActionPackageDeploy.psm1>"

Then run following command:

Invoke-ProvisionActionPlatformInTenant 
    [-LogLevel <LogLevel>] 
    [-LogDirectoryPath <AbsolutePathForLogDirectory>] 
    [-Endpoint <Endpoint>] 
    [-AccessToken <AccessToken>]