Publishing

Publishing basics

Publishing your app makes it easy for Lucid users to find and connect to your app. Lucid provides two publishing options:

Publish to Lucid's Marketplace
- You can request your application be published in Lucid's Marketplace to provide every Lucid user the ability to install your app. Lucid will review your app before it's published to the Marketplace.
Private Publishing
- A Lucid account admin can publish an app privately so only users on your Lucid account can see and access the app in Lucid's Marketplace.

📘
Once an app is published to the Marketplace, it cannot be published privately, and vice-versa.

For apps built on our Extension API, you will be able to publish specific versions of the extension package.
Like a new app, each version of the extension package will be reviewed by Lucid before being released to the marketplace. When the published version changes, users connected to the app are automatically transitioned to the published version.

If you want to distribute your app to only select Lucid users, consider adding them to the app as a collaborator with the Tester role.

📘
Lucid Account Admins can make any published app be connected by default for all users on their account.

Publish to the Lucid Marketplace

This section describes how to publish your app to the Lucid marketplace. Generally, the process for publishing an app is:

Ensure your app meets all publishing requirements.
Submit the app for Lucid review.
Lucid will review the app.
If and when the app passes the review, Lucid will release it to the marketplace.

📘
Publishing to the Lucid Marketplace is not available in the FedRAMP environment. See Lucid's FedRAMP environment.

Publishing requirements

Before requesting your app be published on the Lucid marketplace:

Your app must have an extension package (i.e. be built on our Extension API), an OAuth 2.0 client (i.e. be built on our REST API), or both. See API-specific Requirements for additional requirements specific to which API your app uses.
Your app must have a completed marketplace listing page. This page allows you to explain to potential users the basics of your app (what it does, where to go for support, why your app is incredible, etc.).
You must create a ticket in Zendesk using this form (record the Zendesk ticket ID as you will need to provide it during submission). This ticket gives Lucid the information needed to review your app and is where we ask you any questions that arise during app review.

Submit for review

A user must have the "App owner" collaborator role to request an app be published for the first time (see Application Collaborator Roles). If the application has been previously published, users with the "Code editor" role can also request updates to the app (e.g. new package versions or adding an OAuth 2.0 client) be published. Other collaborators cannot see the UI for publishing.

Submit your new app or update for approval in the Developer Portal, specifically using the Publish application UI in the Publishing section of the app's page. You can also publish a previously approved extension package version (this automatically reverts all users connected to the app to that version).

The steps to publish an app will vary slightly depending on the app's components.

Package version: you can choose which version you want to publish.
OAuth 2.0 client: you will see the name of the client that will be published.
A package version and an OAuth 2.0 client: both are published at the same time.

📘
After you publish an application with only an OAuth 2.0 client, you will be unable to add extension packages to the app in the future.

To submit an app with an extension package for review, you must select the package version (if there is an eligible one) to be published. You can select any package version that has not been revoked, currently published, or under review.

You can publish a previously approved package version at any time, which will trigger an automatic transition to that version for all connected users. Lucid provides this option in case there are unexpected issues with a new version and you need to quickly revert to a stable version.

If your application has an unpublished OAuth 2.0 client, it will be automatically included in the review process.

Click the Publish or Publish new version button to open a modal. If you have previously published your app, the modal will prompt you to pick a version to submit for publishing. If you have not previously published your app, you will be prompted to publish publicly (which this guide is for) or privately. After selecting publicly, you will then be prompted to pick a version to submit. This will trigger either the app review process or publishing if no approval is needed.

📘
The Publish button will be disabled if certain publish requirements have not yet been met. You can hover your mouse over the button to see which requirements have not been met.

If the Lucid review process is required, you will be prompted to enter the Zendesk ticket ID discussed here. You can also find the link to create a Zendesk ticket in the modal.

Once the application has been reviewed and approved by our team, it will be automatically published on Lucid's marketplace.

Refer to the Application publication status to see the updated publication information of your app.

Private publishing

This section describes how to publish your app privately to your account. Unlike publishing to the Lucid marketplace, private publishing does not require any review process, and instead must be performed by someone with account admin permissions (an Account Owner or Account Admin). Private publishing is a feature available to both enterprise and team accounts. An app can be privately published at any time, so long as it meets the following requirements:

Your app must have an extension package (i.e. be built on our Extension API), an OAuth 2.0 client (i.e. be built on our REST API), or both. See API-specific Requirements for additional requirements specific to which API your app uses.
Your app must have a completed marketplace listing page. This page allows you to explain to potential users the basics of your app (what it does, where to go for support, why your app is incredible, etc.).

Submit for private publishing

A user must have the "App owner" collaborator role on an app to publish an app privately for the first time (see Application Collaborator Roles). If the application has already been published privately, users with either the "Code editor" or the "App owner" role can privately publish updates to the app (e.g. new package versions or adding an OAuth 2.0 client). Other collaborators cannot see the UI for publishing.

A user must have account admin permissions (as an Account Owner or Account Admin) to privately publish an app for the first time or privately publish updates to the app.

The steps to privately publish an app will vary slightly depending on the app's components.

Package version: you can choose which version you want to publish.
OAuth 2.0 client: you will see the name of the client that will be published.
A package version and an OAuth 2.0 client: both are published at the same time.

📘
After you publish an application with only an OAuth 2.0 client, you will be unable to add extension packages to the app in the future.

To privately publish an app with an extension package, you must select the package version to be published. You can select any package version that has not been revoked or is currently published.

Click the Publish or Publish new version button to open a modal. If you have previously published your app, the modal will prompt you to pick a version to submit for publishing. If you have not previously published your app, you will be prompted to publish publicly or privately (which this guide is for). After selecting privately, you will then be prompted to pick a version to publish. This will trigger private publishing immediately.

📘
The Publish button will be disabled if certain publish requirements have not yet been met. You can hover your mouse over the button to see which requirements have not been met.

Complete the Marketplace Listing

To complete the Marketplace listing, go to Marketplace listing in the application general section.

In the listing you can provide general information about your application, images, support information, and more.

Applications with only an OAuth 2.0 client must provide a link (or multiple links) redirecting users to the webpage where they can connect to and authorize the app. You can either provide a single link, or one link per Lucid product supported by your application. If your OAuth 2.0-based app supports Lucid multiple products, it is important that the links are entered correctly.

Once you have completed the listing, can see a preview of it and verify everything is perfect.

API-specific requirements

To publish an app (either privately or to the Lucid Marketplace), the app must meet requirements specific to the API it uses. Apps using both APIs must meet both sets of requirements.

REST API

These requirements apply if your application uses our REST API (e.g. has an OAuth 2.0 Client). Refer to the OAuth 2.0 Client Creation Walkthrough for steps on how to create an OAuth 2.0 Client.

📘
Applications built on our legacy REST APIs can not be published.

Requirements:

The name of your OAuth 2.0 client must accurately represent your application. This name will be shown to users when Lucid asks them whether they authorize your app to interact with their data.
Verify you have registered all redirect URIs your application will use.

Extension API

These requirements apply if your application uses our Extension API (e.g. has an extension package). Go to your application in the Lucid Developer Portal and click on the "Packages" tab. In this page, you will be able to see every package version for your application along with the publication status and installation status.

You can click on a package version to see more information about the version, as well as the “Install for me”, “Install for my account”, and “Revoke” options.

📘
You cannot revoke a published package version and revoked package versions cannot be published.

In order to publish your application with a package extension, you must have previously created a package version. If you haven't created one, follow the steps in Upload your extension package to do it. Once you are done, you will see a new entry on the table.

Uploading an extension package

Click your application to open a page with a URL in the form https://lucid.app/developer#/packages/<UUID>. Copy this UUID and paste it into the id field of your manifest.json.

Then, once your editor extension (and other extension package content) works the way you want, you can bundle it for upload to the Lucid Developer Portal with the following command:

npx lucid-package bundle

This creates the file package.zip file which is ready for upload to the Lucid Developer Portal. Go to your application, and click the “Packages” tab. For more information look at our Bundle your package for upload page.

Then, click “+ New Version”, and finally upload and submit the “package.zip” file generated in the previous step.

A new package version will be created, and will be ready to be published. You can follow this process anytime you need to upload new code for your extension package. Remember to update the version field in the manifest.json file as there cannot be repeated versions.

Check your application status

The Publishing section displays information on which users can access your application, if a package version or OAuth 2.0 client is publicly available, and any pending review process.

Every collaborator on the application can see the publication status.

You can also see the publication status of all your apps in the application table.

If you are publishing a new extension package version, every user with the current previous published version will automatically update to the new version.