Best Practices for Building Extensions

Extensions are a pre-built bundle of components that can be installed in your ServiceDesk Plus Cloud account to enhance the functionality of the product. These extensions can be developed and hosted in ManageEngine Marketplace for the benefit of all users.

To ensure the extensions uploaded to Marketplace meet the required standards and consistency in design, follow the guidelines mentioned in this document while building an extension. These guidelines are in no way exhaustive and will be updated as the product evolves.

Naming Conventions

1. The extension name must be contextual and in-line with the functionality offered.
2. Ensure that the name of components built in an extension is:
   • Contextual - This is especially applicable for customization components, extension variables, and connections as users might have to configure them after installing the extension.
   • Unique - This helps in avoiding failure during installation if an extension component and a corresponding component in the production account have the same name. We suggest prefixing your extension's name in your component's name to maintain uniqueness.
3. If you are using our service name in your extension, use the name ServiceDesk Plus Cloud. Avoid using any abbreviations.

General Guidelines

1. Components created via extension cannot be associated with other components in the production account, except for the components under Customization.
2. Make sure that the components built in an extension do not interfere or affect the production account in any adverse way.
3. Do not publish extensions with unused or disabled components.
4. Do not create extensions that will spam the end user with notifications, emails, incidents, etc.
5. You cannot associate users with any extension components. Rather, use roles to allow end users to associate users to that role in their production account.
6. Any major changes in the new version of an extension must clearly be mentioned in the release notes while submitting the extension to the Marketplace.

Component Specific Guidelines

Every component configured must add value to the extension as a whole. Below are the guidelines that must be followed for each component that you intend to use in your extension.

Customization

1. All components under the Customization will be accessed directly by the requesters/technicians. Ensure that they are named appropriately and that they perform the operation as described by their names.
2. Ensure that checklists and checklist items are created with proper details since they cannot be edited in an extension
3. Avoid deleting additional fields in the newer version of an extension as this will result in irreversible loss of data. If you accidentally delete an additional field, reach out to our support.

Templates and Forms

1. If your organization has certain mandatory fields configured in the production setup, we recommend using the default template in your extension. Since extension components cannot be edited in the production setup, organization-specific fields cannot be configured in custom templates.
2. You can create custom templates in your extension if your use case is not solved via the default template. Ensure that the additional fields are used appropriately.
3. Ensure the form rules configured for fields in the default template do not affect the production setup adversely. If your use case is complicated, we recommend configuring form rules over additional fields in a custom template.

Custom Scripts

1. Create scripts specific to your use case and ensure they do not interfere with scripts already present in the users' space.
2. End a custom script with CS.end(). This will signal that the current script execution is complete and initiate ServiceDesk Plus Cloud to process the next script.
3. Do not use IDs of components inside your custom script to perform operations as the IDs will vary in the end user's setup.

Triggers, Business Rules and Workflows

1. Avoid executing custom functions frequently via custom actions by filtering out your use cases specifically in the Criteria section.
2. Do not configure business rules with action set to Abort Process Execution in the extension as it will prevent further business rules in the production setup from being executed.
3. Webhooks and custom functions have daily execution limits in ServiceDesk Plus Cloud. Therefore, ensure that webhooks/custom functions associated as custom actions with a trigger, business rule, or workflow are not invoked very frequently such that the daily execution limit is reached.

Custom Menu

1. Custom menus configured in your extension should be displayed only in contextual areas.
2. The operation performed by a menu item should be conveyed precisely in its name.

Custom Widgets

1. Do not define connections and variables in the widget's manifest file. Create them directly in the extension and use them within your widget's code.
2. Encode and decode data properly in your widget to avoid XSS attacks.
3. Any input that you get from the widget must be validated before being consumed in your widget's code.
4. The current limitation in widgets allows only the OrgAdmin (user who created the extension) to upload and edit widget zip files.
5. Avoid redirecting the user to a different URL (in a new tab) unless necessary.
6. The widgets that you build should be able to run on all ServiceDesk Plus Cloud supported browsers.
7. The fonts that you use in your widget should be legible. We recommend the following fonts - Lato, Open Sans, PT Sans, or Roboto.
8. Maintaining low file size for images and other resources used in widgets will help in loading widgets quickly.
9. Widgets must be responsive and any errors that occur must be captured and handled/displayed appropriately.
10. Any operation that takes time to load should be handled with appropriate loading banners.
11. Perform localization in your widget in locations where content is displayed to end users. Ensure the widget is compatible in all the languages that you support it. Currently, English is the default language.
12. The widget's functionality should be identical in all languages that you have provided.
13. If the custom widget UI requires only the SDAdmin to access and set up the extension, it can be rendered as a configuration widget. Configuration widgets will be displayed only in the extension details page. This will help in isolating the functionality and the configuration parts of the widget.

Custom Functions

1. Certain parameters passed in the context contain information that will be different in the setup where the extension is installed. Use the context in the production setup to build efficient custom functions. For example: Details such as the instance name or extension variables will vary in each setup.
2. Avoid hard coding values in your custom function. Instead, use extension variables to store them so that they can later be edited by the users when the extension is installed in their setups.
3. While using additional fields in custom functions, do not refer to them by their "field key" parameter as it will be different in the installed space. For example: The field key - UDF_CHAR1 in your extension might be changed to UDF_CHAR20 in the user's setup, assuming that end user's space already has additional fields. This will cause the custom function not to work as expected.
4. Do not use IDs of components inside your custom function to perform operations as they will be different in the user's setup.
5. Avoid invoking multiple API calls (invokeurl) in your custom function.
6. Utilize callback functions' URL to serve as an open end point, enabling third-party applications to push data into a custom function in ServiceDesk Plus.

Connections

1. The names of the connections and custom services used should be in-line with the name of your extension. For example: Zylker connection and Zylker service.
2. The authorization used in your custom service should be clearly documented to avoid confusion while setting up the connection after the extension has been installed.
3. Your connections should have only the permissions required to perform the configured operation in the product. For example: if your connection is meant to read data via a custom function, its scope should be "read" and not contain create, delete, etc.
4. Avoid updating the connection's scopes or configurations as the end user will have to re-authenticate it to resume normal operation. This can cause downtime in the user's production instance.

Custom Modules

1. Only 20 custom modules can be added to a service desk instance. Therefore, use custom modules in your extension only if needed. If the limit is exhausted, extension installation will fail.
2. Only store necessary data in your custom module. Stored data must be accessible to admins.
3. Consider using extension variables if you only have a few sets of key-value data to be stored for the functioning of your extension.

Extension Variables

1. Avoid using read-only extension variables unless necessary.
2. Configure editable extension variables only if users are required to provide values post-installation.
3. Ensure the Value field in an editable extension variable is empty before publishing the extension.
4. The API name of an extension variable will be prefixed with the extension's instance name. Therefore, name your extension properly to avoid inconsistencies in the variables' API names if you rename your extension.

Extension Scripts

1. The After Extension Installation custom function will be invoked only while installing an extension. It will not be invoked while updating extension.
2. Changes or components added via the After Extension Installation custom function must be reverted or cleared by Before Extension Uninstallation custom function.

Usage of AI and Generative content

1. If your extension sends data to be processed by third party AI APIs, you have to mention the type of data (payload) that is being sent explicitly in your Terms of use document.
2. Avoid configuring Personally Identifiable Information (PII) in AI or third party APIs.
3. Ensure the generated response in prompts is tailored for professional use. Avoid using abusive/offensive/coarse text.

Publishing Extension

1. For privately-published extensions, ensure that the link is shared only with the intended users. You can use Generate New Link option in the extension builder to invalidate the existing private link and generate a new link.
2. Only the Organization Admin (user who created the first extension) can publish extensions - privately and to the marketplace.
3. To host your extension in a different DC marketplace (e.g. you could be in US DC and list your extension in EU DC), ensure your extension follows the guidelines of those regions to be eligible for listing.

Payments, Pricing and License

1. As the developer (vendor), you can decide if a paid extension can have a trial period before it is purchased.
2. During the trial, all functionalities of the extension will be supported.
3. After the trial expires, the extension's components will be disabled and they will be enabled after the payment is completed.
4. If an extension's pricing is updated from free to paid, functionalities offered to existing users will not be affected.
5. If your extension allows integration with a third-party application that requires separate free or paid accounts, mention it clearly in the help documentation.

Submission Guidelines

General Guidelines

1. Do not provide advertisements related to your app or any third-party app in the extension.
2. Avoid submitting duplicates of your extension by making minor changes for a specific set of users.
3. Any major change in a new version must clearly be mentioned in the release notes while submitting that extension to the marketplace.
4. For more details, check out our Content Submission Guidelines.

Screenshot Guidelines

1. Do not add any marketing information in the screenshots used in the marketplace. They should only explain the functionality of the extension.
2. Use only screenshots depicting the usage of your extension in ServiceDesk Plus Cloud.
3. You can include a maximum of 2 screenshots depicting the third-party app which you are integrating with ServiceDesk Plus Cloud.
4. The first screenshot that you provide should cover what your extension offers, as this will be in an expanded view in the Screenshots tab, by default.

Video Guidelines

1. The video must only showcase the functionality of the extension.
2. Do not enable advertisements in the published video.
3. Do not disable or take down the video after the extension is hosted in the marketplace.
4. Video should be hosted publicly on Youtube.
5. We recommend the video be a minute long and not longer than 2 minutes.

Contact and Support Information

1. The contact information you provide should be valid. Ensure you can promptly respond to queries raised by end users.
2. Do not provide support links that require the user to login in order to access support page or any other external service.