Self-hosting Automation Catalog documentation (eng)

Configuring Power Catalog (eng)

Follow the steps mentioned here to set up and administer a Power Catalog: Administer the catalog - Power Platform | Microsoft Learn

Connecting Automation Catalog to Power Catalog (eng)

Add the URL of the required environment in environment variables in your ADO Pipeline or Github Workflow.

Add Catalog Extension Metadata zip

Import the CatalogExtension_1_0_1_3.zip present in the repository, in the environment where the catalog is created.

Adding A3P templates to Power Catalog (eng)

Open Power Catalog Manager App. Select Catalog Publishers and create a new publisher. Note the Publisher Name and the Publisher ID.

Install Pac cli. Use this documentation: Microsoft Power Platform CLI - Power Platform | Microsoft Learn

In the repository, Templates folder has all the Catalog items that need to be submitted in your target catalog.

In the Templates folder, each catalog item folder has a SubmissionDoc.json and a zip file.

Run update-submission-docs.ps1 – PowerShell script. Enter publisher ID, publisher name, Engineering contact details and support contact details when prompted while running the PowerShell script. This will update the above fields inside each SubmissionDoc json file.

Once the over script ran successfully, run submit-to-catalog-script.ps1 – PowerShell script. Enter the organization url.

To get thorganization url - Go to power apps home page. Choose the environment where the catalog is created. Click on settings -> Developer resources. Copy the Web API endpoint base url.

Deployment of Azure Scripts (Bicep)

To Do Prerequisites:

1. Clone the repository:

Clone the repository and open it in Visual Studio Code. Automation-Catalog-for-Power-Platform

2. Create an enterprise subscription:

1. Create an azure subscription or use an existing subscription. (Create an Enterprise Agreement subscription - Azure Cost Management + Billing | Microsoft Learn )

2. Make a note of the subscription ID

3. Create an app registration:

1. Create an application registration (Quickstart: Register an app in the Microsoft identity platform - Microsoft identity platform | Microsoft Learn )

2. While creating the app registration, use the default options.

3. Make a note of client ID and tenant ID from the app registration

Configuring Azure DevOps

4. Create a service connection in Azure DevOps:

Create a service connection (Service connections - Azure Pipelines | Microsoft Learn )

Use the following details, while creating a service connection.

1. Type: Azure Resource Manager

2. Authentication Method: Service Principal (automatic)

3. Scope Level: Subscription

4. Resource Group: (none)

5. Service connection name:

Make a note of service connection name.

5. Create an environment in Azure DevOps:

Create an environment (Create and target environments - Azure Pipelines | Microsoft Learn )

Use the following details, while creating an environment.

1. Name:

2. Resource: None

Go to ‘Approvals and Checks’, and create an ‘Approvals’ check. Add people who may have to approve before deploying code into the resources.

Make a note of environment name.

6. Create the pipeline:

1. Navigate to the Azure Pipelines and create a new pipeline and select a location for the pipeline.

2. Select the code location as ‘Azure DevOps’ and select the repository ‘Automation-Catalog-For-PowerPlatform’

3. Configure the YAML pipeline by selecting an existing YAML file ‘AutomationCatalogForPowerPlatform-DeployResources.yml’ and click ‘Review Pipeline’

4. Save the pipeline.

7. Add Pipeline variables:

1. Open the pipeline in Azure DevOps

2. Click on variables and add the following variables.

3. Add the values for all the variables. Service Connection and environment names are the same used while creating them in the previous steps.

Variable Name	Can be referenced from
poolName	Name of the pool that should be used to run the pipeline (Open you Azure DevOps. Go to Project settings-> Agent Pool to get this information)
serviceConnection	Refer in the same document - (Create a service connection in Azure DevOps)
Environment	Refer in the same document - (Create an environment in Azure DevOps)
ClientId	Refer in the same document - (Create an app registration)
TenantId	Refer in the same document - (Create an app registration)
SubscriptionId	Refer in the same document - (Create an enterprise subscription)
appService	Give your own name
appServicePlan	Give your own name
applicationInsights	Give your own name
storageAccount	Give your own name (*Storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only.)
ResourceGroupName	Give your own name
location	Give location of your preference where the resource group and resources should be present (eg: westus2)
catalogEnvUrl	URL of the environment associated with the catalog
catalogPublisherId	ID of the catalog publisher created
teamsAppId	Keep this empty. This variable should be set later.
feedbackFormUrl	URL to your feedback form
faqUrl	URL where FAQs are going to be present
adminEnvironment	Default Environment ID
AppInsightsConnectionString	Keep this empty. This variable should be set later.

8. Role Assignment:

The service connection creates the resource group and resources when the pipeline is ran using bicep templates.

Give the following roles to the service connection at subscription level.

Assign Azure roles using the Azure portal - Azure RBAC | Microsoft Learn

Go to your subscription, click on the ‘Access Control (IAM)’ and assign the following roles

1. ‘Corp Tenant DevOps Role’ //MS specific

2. ‘Contributor’

3. ‘Role Based Access Control’ (Revoke this access after deploying resources)

9. Run pipeline:

1. Run the pipeline which got created in the above step.

2. Make sure to tick the checkbox to Deploy resources.

3. Permit use of service connection when prompted.

4. Permit the environment to access/run the pipeline.

10. Role Assignment

When the pipeline ran successfully, assign the following role.

Go to the storage account that got created in the resource group, click on the ‘Access Control (IAM)’.

Assign the following role ‘Storage Blob Table Contributor’ to the ‘appService’ that has been created in the resource group in the Azure subscription.

Configuring GitHub

4. Create a resource group

Create a resource group in the azure portal. Make note of the name and the location selected. (Create a resource group)

5. Create a user assigned managed identity and add federated credentials in the identity:

Create a user assigned managed identity in azure portal. Choose an existing resource group or create new one if needed. (Create a user-assigned managed identity | Microsoft Learn )

1. To authenticate successfully to github, create federated credentials in the identity. Open the user assigned managed identity and open federated credentials.

2. Fill in the following details

Federated Credential Scenario	Configure a GitHub issued token to impersonate this application and deploy to Azure
Issuer	[Refer in the same document - (Create an app registration)](https://token.actions.githubusercontent.com)
Organization	(Refer the organization name from github)
Repository	(Refer the repository name from github)
Entity	Branch
Branch	main

Give a name to the credential and save it.

6. Create github actions workflow:

1. Navigate to the Github actions tab.

2. Workflows are already created from the yml present in .github/workflows/build-and-deploy-code.yml and .github/workflows/deploy-resources.yml

7. Add Pipeline variables:

1. Open the settings tab in Github.

2. Click on secrets and variables and add the following variables and secrets.

3. Add the values for all the variables. Service Connection and environment names are the same used while creating them in the previous steps.

Secret Name	Can be referenced from
AZURE_CLIENT_ID	Refer in the same document - (Create an app registration)
AZURE_TENANT_ID	Refer in the same document - (Create an app registration)
AZURE_SUBSCRIPTION_ID	Refer in the same document - (Create an enterprise subscription)
AZURE_FIC_CLIENT_ID	Refer in the same document - (Create a user assigned managed identity)

Variable Name	Can be referenced from
APPSERVICE	Give your own name
APPSERVICEPLAN	Give your own name
APPLICATIONINSIGHTS	Give your own name
STORAGEACCOUNT	Give your own name (*Storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only.)
RESOURCEGROUPNAME	Resource group created in earlier
LOCATION	Give location of your preference where the resource group and resources should be present (eg: westus2)
CATALOG_ENV_URL	URL of the environment associated with the catalog
CATALOG_PUBLISHER_ID	ID of the catalog publisher created
TEAMSAPPID	TEAMSAPPID_PH <This is a placeholder and should be used till a value is set.>
FEEDBACKFORMURL	FEEDBACKFORMURL_PH <This is a placeholder and should be used till a value is set.> URL to your feedback form
FAQURL	FAQURL_PH <This is a placeholder and should be used till a value is set.> URL where FAQs are going to be present
ADMINENVIRONMENT	Default Environment ID
APPINSIGHTSCONNECTIONSTRING	Keep this empty. This variable should be set later.

8. Role Assignment:

The managed identity should be given permissions to create the resource group and resources when the pipeline is ran using bicep templates.

Give the following roles to the identity at subscription level.

Assign Azure roles using the Azure portal - Azure RBAC | Microsoft Learn

Go to your subscription, click on the ‘Access Control (IAM)’ and assign the following roles

1. ‘Contributor’

2. ‘Role Based Access Control’ (Revoke this access after deploying resources)

9. Run workflow:

1. Run the deploy-resources workflow which got created in the above step.

10. Role Assignment

When the workflow ran successfully, assign the following role.

Add federated credentials to the app registration with the for the system-assigned managed identity of the app service.

Go to the storage account that got created in the resource group, click on the ‘Access Control (IAM)’.

Assign the role ‘Storage Blob Table Contributor’ to the App Service that has been created in the resource group in the Azure subscription.

11. Update Manifest File:

1. Open the repository in Visual Studio Code and navigate to ‘AutomationHub.Client/manifest’ directory. This directory has a manifest.json file, color.png and outline.png

2. Open manifest.json and replace the following metadata in the manifest file

       a. Look for <> in the json file. Replace it with name of the appService. Give the same name as given in step 5 - Update the pipeline variables

       b. Look for <> in the json file. Replace it with Client ID. Give the same value as in step 2 - Create an app registration

3. Save the json file and zip the manifest directory.

12. Update App Registration:

1. From the manifest, copy the “webApplicationInfo: resource“.

2. Open the app registration we created earlier, and click on Manage>Expose an API.

3. Add Application ID URI, and paste the value we copied from manifest file and save it.

4. In the "Expose an API" screen, add a scope access\_as\_user, with consent set to Admin only.

5. In the "Expose an API" screen, add client applications "1fec8e78-bce4-4aaf-ab1b-5451cc387264", "5e3ce6c0-2b1f-4285-8d4b-75ee78787346" with the above scope.

6. Go to "Manifest" and update accessTokenAcceptedVersion key to 2

7. Make sure admin consent has been granted for the following scopes to your app registration:

   1. Graph user.read
   2. Dynamics.CRM user_impersonation

13. Sideload App:

Use the following instructions for sideloading the zip file

1. Open teams app and choose Apps in the left side pane.

2. Click on Manage your Apps and select Upload an app.

3. Upload the created zip file.

On the first load, if there are no items in the connected catalog, a spinner will show indefinitely.

14. Publish App to Teams:

Publish App on Teams Store - Teams | Microsoft Learn Use the instructions in the above link and publish the teams app. Please note that you may need to reach out to the admin team to understand any tenant-specific steps.

15. Note App Insights Connection String Value:

Open the application insights that got created. Open Configure->Properties and make note of the connection string present there.

16. Add Pipeline variable (Azure DevOps)

1. Open the pipeline in Azure DevOps
2. Click on variables and update the value the following variable, after publishing the app to teams and re-run the pipeline.

Variable Name	Can be referenced from
teamsAppId	Teams App ID from the publishing process
AppInsightsConnectionString	Application Insights Connection String noted from previous step

17. Add Repository Variable (Github)

1. Open the repo in Github, navigate to the Settings page, and select "Actions" under "Secrets and Certificates".
2. Update the following variables.

Variable Name	Can be referenced from
TEAMSAPPID	Teams App ID from the publishing process
APPINSIGHTSCONNECTIONSTRING	Application Insights Connection String noted from previous step

Troubleshooting

1. While running the pipeline, if you see an error of the kind: MissingSubscriptionRegistration: The subscription is not registered to use namespace 'Microsoft.Web'. Follow the steps mentioned here: Resource provider registration errors - Azure Resource Manager | Microsoft Learn