Using the catalog with Power Platform CLI
The catalog in Power Platform enables developers and makers to:
- Crowd-source and find templates and components within their environment easily.
- Find and install the latest and authoritative version of a component.
- Get started with templates and components that provide immediate value.
Before you can work with catalog items, you must install and configure it. More information: Administer the catalog
Application makers and developers can submit items to the catalog so that they can help their colleagues solve business problems.
Important
Managed environments are required to submit items to the catalog. However, you can install items from any environments. Learn more about managed environments
Get started
Install Power Platform CLI
Follow the steps to install Power Platform CLI: Install Microsoft Power Platform CLI
Get access to catalog as submitter or reader
Contact your administrator to grant access to the catalog. You need the Catalog Submitter security role to be associated with your user account or a team that you belong to. More information: Edit user access
Use the catalog
After you have installed the Power Platform CLI, you must create an authentication profile using the pac auth create command. Using the authentication profile for the environment where the catalog is installed, you can perform the following tasks using PAC CLI:
- View available catalogs in your tenant
- View items in the catalog
- Install items from the catalog
- Submit items to the catalog
- Check status of catalog submissions
View available catalogs in your tenant
Use the pac admin list command to view the catalogs available in your tenant.
Note
This command requires an administrator authentication profile.
When using this command, you must use the following --application parameter with the value 83a35943-cb41-4266-b7d2-81d60f383695.
pac admin list --application 83a35943-cb41-4266-b7d2-81d60f383695
83a35943-cb41-4266-b7d2-81d60f383695 is the application ID associated with the catalog.
View items in the catalog
Use the pac catalog list command to view items in the catalog.
pac catalog list
Connected to... TestCatalog
Connected as user@domain
Listing all published catalog items from the current Dataverse Organization...
Catalog Item Name Publisher Name Catalog Item Id Revision Id Version Status
Contoso Conference Custom Connector Catalog Conferences Team ContosoConferencesCustomConnector 4e882dd6-74f3-ed11-8849-000d3a0a286b 1.0.0.1 Published
Contoso Themed Components ContosoPublisher ContosoThemedComponents efbc469d-f1b2-ed11-83fd-000d3a0a2d9d 1.0.0.1 Published
Install items from the catalog
Use the pac catalog install command to install items from the catalog.
pac catalog install -tu https://<your org>.crm.dynamics.com/ -cid ContosoConferencesCustomConnector
Connected to... TestCatalog
Connected as user@domain
ContosoConferencesCustomConnector
Tracking id for this installation is 202012ec-80f3-ed11-8849-000d3a0a2d9d
Submit items to the catalog
To submit an item to the catalog, you need:
- A solution or package deployer package containing the item you want to submit
- A submission metadata JSON document
Use the pac catalog create-submission command to get an example submission metadata JSON document. You must edit this document and more submission attributes can be added. More information: Submission attributes
After your submission metadata JSON document is ready, use the pac catalog submit command to submit it.
pac catalog submit -p "BuildDemoSubmission.json" -sz "ContosoConference_1_0_0_1_managed.zip"
Creating package for catalog submit request...
Connected to... TestCatalog
Connected as user@domain
Tracking id for this submission is 0e6b119d-80f3-ed11-8849-000d3a0a2d9d
Check status of catalog submissions
Use the pac catalog status command to check the status of catalog submissions.
pac catalog status --tracking-id 0e6b119d-80f3-ed11-8849-000d3a0a2d9d --type submit
Connected to... TestCatalog
Connected as user@domain
Status of the Submit request: Submitted
Submission attributes
Before you can submit items to a catalog, you must prepare a JSON document that describes the items you want to submit. More information: Submit items to the catalog
To help you, the pac catalog create-submission command generates a sample submission.json file.
Note
More attributes are supported in the submission file and those are covered in the subsequent section.
You need to edit this file to submit an item. Here's an example submission created from the JSON above.
{
"modelVersion": "1.0.0.0",
"operation": "CreateOrUpdate",
"sourcePortal": 526430005,
"businessJustification": "Power Platform custom connector for Conference API",
"publisherDetails": {
"publisherId": "ContosoConferencesTeam",
"publisherDisplayName": "Catalog Conferences Team"
},
"catalogItemDefinition": {
"id": "ContosoConferencesCustomConnector",
"displayName": "Contoso Conference Custom Connector",
"description": "Demo Custom connector to query Conference Speakers & Sessions",
"offer": {
"type": "Component_Collection",
"deploymentType": "Normal",
"engineeringName": {
"firstName": "Jennifer",
"lastName": "Wilkins",
"email": "jwilkins@contoso.com",
"phoneNumber": "555-111-1234"
},
"supportName": {
"firstName": "Aidan",
"lastName": "Hunt",
"email": "ahunt@mouse.com",
"phoneNumber": "555-111-1234"
}
}
}
}
Required data
The following items are required for all submissions:
Publisher
Creates a publisher record that can be associated to one or more Microsoft Entra ID groups containing authorized users who can make updates to the catalog item going forward.
Don't confuse this term with Solution Publisher. Catalog item publisher isn't used with solutions.
You need to provide the ID publisher DisplayName at a minimum. ID can be any string value. The system checks if that publisher exists, else creates it and assigns an ID.
For example, HR IT team of developers can create a publisher and ID the developers using a Microsoft Entra ID group.
Here's a sample of a publisher record:
"publisherDetails": {
"publisherId": "MyPublisherId",
"publisherDisplayName": "Contoso Publishing",
"publisherUpnList": [
{
"action": "Add",
"upn": "john.doe@contoso.com"
}
],
"publisherAADGroupOIDS": [
{
"action": "Add",
"groupName": "PowerCatalogSubmitters",
"groupOID": "2ded6de9-ab44-4478-9bd4-e609947daa2e",
"groupType": "Security"
}
]
}
Catalog item
The actual Power Platform solution. A package is what is stored in the catalog.
id and displayName are mandatory. description and businessCategories are optional.
Seeded business categories list of value is in the appendix. ComponentUsedInApplication is for future use only.
Here's an example of a catalog item including its engineeringName and supportName contacts that are mandatory.
"catalogItemDefinition": {
"id": "ContosoTravelsApp",
"displayName": "Contoso Travel Expense App",
"description": "Submit expenses on the go!",
"offer": {
"businessCategories": [526430000, 526430001, 526430002],
"type": "Component_Collection",
"deploymentType": "Normal",
"small48x48Image": {
"name": "Small48Image",
"fileSasLink": "https://www.contoso.com/icon48.jpg"
},
"large216x216Image": {
"name": "Large216image2",
"fileSasLink": "https://www.contoso.com/icon216.jpg"
},
"documents": [
{
"name": "ImaNewfile",
"fileSasLink": "https://www.contoso.com/screenshot1.jpg"
},
{
"name": "ImaNewfile2",
"fileSasLink": "https://www.contoso.com/screenshot2.jpg"
}
],
"helpLink": "https://www.contoso.com/help.html",
"privacyPolicyLink": "https://www.contoso.com/privacy.html",
"legalTerms": "https://www.contoso.com/legal.html",
"engineeringName": {
"firstName": "John",
"lastName": "Roon",
"email": "john@contoso.com",
"phoneNumber": "999-111-1234"
},
"supportName": {
"firstName": "Jane",
"lastName": "Drill",
"email": "jane@contoso.com",
"phoneNumber": "999-111-1234"
}
}
}
Engineering contact
Developer product contact.
Contact that the consumer of catalog item can reach out to if they have technical questions to extend or reuse the app for another purpose.
"engineeringName": {
"firstName": "String"
"lastName": "String (required)"
"email": "String (required)"
"phoneNumber": "String"
}
Example
"engineeringName": {
"firstName": "John",
"lastName": "Roon",
"email": "john@contoso.com",
"phoneNumber": "999-111-1234"
},
Support contact
IT support specialist.
Can be same as the engineering contact that the consumer of a catalog item can reach out to if they run into issues with the application.
"supportName": {
"firstName": "String"
"lastName": "String (required)"
"email": "String (required)"
"phoneNumber": "String"
}
Recommended data
The following items are highly recommended, but not required.
small48x48image
Provide information of the icon to be displayed in maker or other discovery UI. If you don't provide this image a system default icon is used.
"small48x48image":{
"name": "String",
"fileSasLink": "Fully qualified publicly accessible url"
}
Documents
You can pass screenshots here of your application to help makers identify whether this app provides the functionality or capability they're looking for.
The most common thing people do before downloading an app or template is look at its images and screenshots to understand the capabilities instead of reading the description.
{
"name": "String",
"fileSasLink": "Fully qualified publicly accessible url"
}
Help link
URL link to help documentation.
Fully qualified URLs your users are able to access. These URLs can be links to internal docs or sharepoint resources.
"helpLink": "https://www.yourcompany.com"
The following items are optional
Source portal
Source of submission.
When submitting from the Power Platform CLI, use 526430005 as the Source Portal value. For other sources, use 526430000.
Business categories
One or more of the business categories can be included in the submission from the list below.
| Code | Description |
|---|---|
| 526430000 | Customer Service |
| 526430001 | Project Management |
| 526430002 | Calendar Management & Scheduling |
| 526430003 | Email Management |
| 526430004 | Files & Documentation |
| 526430005 | Notification & Reminders |
| 526430006 | Analytics |
| 526430007 | Collaboration |
| 526430008 | Commerce |
| 526430009 | Finance |
| 526430010 | Compliance & Legal |
| 526430011 | Sales |
| 526430012 | IT Tools |
| 526430013 | Marketing |
| 526430014 | Operations & Supply Chain |
| 526430015 | Internet of Things |
| 526430016 | AI Machine Learning |
| 526430017 | Geolocation |
| 526430018 | Human Resources |
Currently, new business categories can't be configured.
Operation
Possible values:
CreateOrUpdateCreateUpdateDisabled
Use CreateOrUpdate for new submissions.
"operation": "CreateOrUpdate"
Business justification
Explains the business value created by this catalog item. This information is visible to approvers and appears in the planned consumption experience in the maker discovery user experience.
Users can say their submission helps with cost reduction or productivity, for example. Some organizations require certain classes of value and those values can be entered here.
String can contain HTML, or Rich Text (RTF).
"businessJustification": "Submit your travel expenses!"
large216x216Image
Provide information of the icon to be displayed in the maker or other discovery UI.
Some user experiences uses larger icons to render cards for discovery.
name: String
fileSasLink: fully qualified publicly accessible url
LogicalName: string, for future use, ignored
recId: guid, for future use, ignored
attributeName: string, for future use, ignored
An example of the image metadata.
"large216x216Image": {
"name": "Large216image2",
"fileSasLink": "https://mywebsite/largeicon.jpeg"
},
Privacy policy
URL link to pertinent policies.
Policies regarding careful usage of the component or application being submitted.
"privacyPolicyLink": "https://www.mycompany.com/privacy.html"
Legal terms
URL link to pertinent terms and conditions.
Any legal terms or internal guidance for evaluation of the consumer of the catalog item.
"legalTerms": "https://www.mycompany.com/legalterms.html"