Skip to content

Commit f6b0f3f

Browse files
MhcVintarMhcVintar
committed
ISS-120468: Update documentation for the marketplace related commands
Added documentation regarding marketplace listings. https://app.devrev.ai/devrev/works/ISS-120468
1 parent 889a51e commit f6b0f3f

File tree

1 file changed

+239
-0
lines changed

1 file changed

+239
-0
lines changed

‎fern/docs/pages/references/marketplace-listings.mdx

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Publish an item to Marketplace
2+
3+
Welcome to the documentation page for publishing marketplace listings to the DevRev marketplace using the DevRev CLI.
4+
This guide will walk you through the process of submitting your listing, reviewing it, and publishing it for users to
5+
access and engage with. You will learn about creating and updating marketplace submissions, the roles of the marketplace
6+
publisher and admin, and the steps involved in getting your submission approved. Whether you're new to the DevRev CLI or
7+
looking for a refresher, this documentation will provide you with the necessary information to navigate the publishing
8+
process seamlessly. Let's dive in and get started!
9+
10+
## Table of Contents
11+
12+
- [Publish an item to Marketplace](#publish-an-item-to-marketplace)
13+
- [Table of Contents](#table-of-contents)
14+
- [Glossary](#glossary)
15+
- [Marketplace](#marketplace)
16+
- [Marketplace Submission](#marketplace-submission)
17+
- [Marketplace Item](#marketplace-item)
18+
- [Marketplace listing](#marketplace-listing)
19+
- [Publishing process](#publishing-process)
20+
- [Get Started](#get-started)
21+
- [Create a Snap-In](#create-a-snap-in)
22+
- [Create marketplace listing](#create-marketplace-listing)
23+
- [Initial submission](#initial-submission)
24+
- [New submission for an existing marketplace item](#new-submission-for-an-existing-marketplace-item)
25+
- [Update marketplace submission](#update-marketplace-submission)
26+
- [Publish marketplace submission](#publish-marketplace-submission)
27+
- [Delete marketplace submission](#delete-marketplace-submission)
28+
- [Auto-upgradation of marketplace-items](#auto-upgradation-of-marketplace-items)
29+
- [Sharing marketplace listings](#sharing-marketplace-listings)
30+
- [Ranking marketplace listings](#ranking-marketplace-listings)
31+
- [Some helpful commands](#some-helpful-commands)
32+
33+
## Glossary
34+
35+
### Marketplace
36+
37+
A marketplace serves as a platform for creators and consumers to collaborate, engage, and conduct transactions. It
38+
provides an avenue for distributing your products and services, thereby enabling you to generate revenue from them.
39+
40+
### Marketplace Submission
41+
42+
This object is utilized for submission purposes when the marketplace publisher is either creating a new listing for the
43+
marketplace or updating an existing one.
44+
45+
### Marketplace Item
46+
47+
Any item in marketplace listings that is available for installation.
48+
49+
#### Marketplace listing
50+
51+
Marketplace listing refers to all the marketplace items that belong to the same marketplace and have the same slug. It
52+
is also important to note that at most one marketplace item, belonging to a specific marketplace listing, can be in the
53+
`Published` state.
54+
55+
![marketplace listing](./res/images/marketplace-listing.png)
56+
57+
## Publishing process
58+
59+
The publishing process begins by initiating a marketplace submission, which entails requesting the creation of a new
60+
marketplace listing or updating an existing one. The submission is created by the marketplace publisher and subsequently
61+
reviewed by the marketplace admin. Once the submission is ready for review, the publisher must transition it to the '
62+
waiting for review' state. During this phase, the marketplace admin conducts a review and decides whether to approve or
63+
reject the submission. If the submission is approved, the marketplace publisher can proceed to publish it. However, if
64+
the submission is rejected, the publisher has the option to make updates and resubmit it for another round of review.
65+
66+
![life cycle](./res/images/lifecycle.png)
67+
68+
## Get Started
69+
70+
To get started with publishing a marketplace item, you will need the DevRev CLI. For CLI related
71+
guide [visit here](https://github.com/devrev/snap-in-docs/blob/main/references/cli.md).
72+
73+
### Create a Snap-In
74+
75+
To proceed with making a submission in the marketplace, you will need a Snap-In for which we will create this
76+
submission. If you are new to
77+
Snap-Ins, [follow this guide here](https://github.com/devrev/snap-in-docs/blob/main/start.md), to create your first
78+
Snap-In.
79+
80+
## Create marketplace listing
81+
82+
When creating a new marketplace listing, we have to create an initial submission where we provide all the mandatory
83+
properties (e.g. name, description, icon, etc.).
84+
85+
### Initial submission
86+
87+
To create a new marketplace listing, run the following command, which will start a __wizard__ to guide you through the
88+
process:
89+
90+
```bash
91+
devrev marketplace_submissions create
92+
```
93+
94+
### New submission for an existing marketplace item
95+
96+
When a marketplace listing already exists (there is at least one marketplace item in the `published` or `end_of_sale`
97+
state), we can modify the listing by creating a new submission. First we have to create a submission which we can later
98+
update
99+
as desired.
100+
101+
To create a new submission for an existing marketplace listing, run the following command, which will start a __wizard__
102+
to
103+
guide you through the process:
104+
105+
```bash
106+
devrev marketplace_submissions create
107+
```
108+
109+
## Update marketplace submission
110+
111+
Once a submission has been created, it can be updated by running the following command, which will start a __wizard__ to
112+
guide you through the process:
113+
114+
```bash
115+
devrev marketplace_submissions update
116+
```
117+
118+
## Publish marketplace submission
119+
120+
The newly created marketplace submission is in the `draft` state. In order to publish it, we first have to transition it
121+
to`waiting_for_review` state. This can be done by running the following command, which will start a __wizard__ to guide
122+
you through the process:
123+
124+
```bash
125+
devrev marketplace_submissions transition
126+
```
127+
128+
Once the submission is transitioned to the `waiting_for_review` state, it needs to be approved by a marketplace admin.
129+
While in review, the state of the submission is `in_review`. Once it is reviewed, the state will be changed to either
130+
`approved` or `rejected`.
131+
132+
<Callout intent="note">
133+
Submissions whose state is `in_review` cannot be modified.
134+
</Callout>
135+
136+
137+
If the submission was rejected, we can transition it back to `draft` state and modify it to satisfy the requirements.
138+
Once the submission is updated, we can transition it back to `waiting_for_review` state to be reviewed again.
139+
140+
If the submission was approved, we can publish it using the following command, which will start a __wizard__ to guide
141+
you through the process:
142+
143+
```bash
144+
devrev marketplace_items publish
145+
```
146+
147+
To make sure that marketplace item was published we can retrieve it using its ID:
148+
149+
```bash
150+
devrev marketplace_items show "<id>" | jq "{name: .name, id: .id}"
151+
```
152+
153+
## Delete marketplace submission
154+
155+
If a marketplace submission was created by mistake or is no longer relevant, it can be deleted. However, deletion of a
156+
marketplace submission is only permitted for the owners of the submission and is restricted to submissions that are in
157+
the `draft` or `rejected` state. You can delete a submission using the following command, which will start a __wizard__
158+
to guide you through the process:
159+
160+
```bash
161+
devrev marketplace_submissions delete
162+
```
163+
164+
## Auto-upgradation of marketplace-items
165+
166+
For marketplace-items that are Snap-Ins, auto-upgradation is also supported.
167+
Once a new version for a marketplace-item is published, the respective Snap-Ins will be auto-upgraded to the latest
168+
version.
169+
170+
However, there are some criteria that need to be met for auto-upgrade to work:
171+
172+
- The upgrade should not require any user input/action.
173+
- There should not be any new global variables added.
174+
- There should not be any new connections that needs to be configured.
175+
176+
## Sharing marketplace listings
177+
178+
By default, all marketplace listings are accessible to all users. However, if someone wants to share a specific
179+
marketplace listing with certain organizations only, they should follow the steps below:
180+
181+
- When creating an initial submission, property __access level__ should be set to `restricted`.
182+
- Proceed through the review process to obtain approval for the submission.
183+
- Once the submission is approved, publish it to create the marketplace item.
184+
- To invite a specific DEV organization to the newly created marketplace item, execute the following command:
185+
186+
```bash
187+
devrev marketplace_items invite [marketplace_item_id] [dev_org_id]
188+
```
189+
190+
Example:
191+
192+
```bash
193+
devrev marketplace_items invite "don:integration:dvrv-us-1:devo/123:marketplace/456:marketplace_item/789" "don:identity:dvrv-us-1:devo/456"
194+
```
195+
196+
Once an organization is invited to a marketplace listing, their members can *view* and *install* it within their own
197+
organization.
198+
199+
When a marketplace listing is marked as restricted, it is possible to change the access level to `public`. However,
200+
the reverse process, changing the access level from `public` to `restricted`, is not permitted.
201+
202+
When a marketplace listing is shared with an organization, this information is **retained when creating new submissions
203+
for the same listing**. Additionally, automatic upgrades function seamlessly, just like in the case of public
204+
marketplace listings.
205+
206+
## Ranking marketplace listings
207+
208+
The items listed on the marketplace are arranged based on the `meta_score` property, with those having higher scores
209+
appearing at the top of the list. To manage the `meta_score` property, a dedicated API called `marketplace-items.rank`
210+
is utilized. To update the `meta_score`, one needs to provide the `marketplace item ID` along with the desired score (
211+
within the allowed range of values: [1, 100000]):
212+
213+
```bash
214+
devrev marketplace_items rank "<marketplace_item_id>" "<meta_score>" | jq
215+
```
216+
217+
<Callout intent="note">
218+
Please note that API usage is restricted exclusively to `DEV-0` users.
219+
</Callout>
220+
221+
## Some helpful commands
222+
223+
List marketplaces:
224+
225+
```bash
226+
devrev marketplace list | jq "{name: .name, type: .marketplace_type, id: .id}"
227+
```
228+
229+
List marketplace items (by default, listings are from universal marketplace):
230+
231+
```bash
232+
devrev marketplace_items list | jq "{name: .name, id: .id, type: .type}"
233+
```
234+
235+
List marketplace items in **organizational** marketplace:
236+
237+
```bash
238+
devrev marketplace_items list --marketplace "<id>" | jq "{name: .name, id: .id, type: .type}"
239+
```

0 commit comments

Comments
 (0)