Prerequisites and top-tips for creating a custom extension

Created by James Hurrell, last modified on Feb 06, 2020



Summary: A list of prerequisites and top-tips for creating your own custom extension.

GitHub account

You need a GitHub account to store the custom extension's source code and documentation. If you already have an account you can use this, but if not, you will need to create a new one - see https://github.com/join.

Please note:

  • the GitHub account must be a "public" account
  • the account you use to access the CAST Extend website is not linked to GitHub and therefore if you do not already have your own GitHub account you will need to create a new GitHub account specifically to create the custom extension. You can use the same credentials (login/password) that you use for the CAST Extend website, but this is not mandatory.

Membership of the CAST-Extend GitHub organization

You need to become a member of the CAST Extend organization. At the current time, please contact the GitHub user "CASTNDO" who will be able to add you to the organization. You will receive an email from GitHub (in the mailbox used for your GitHub account) containing a link which you need to click to confirm the membership.

You will also require "create new repository" privileges in the CAST Extend organization. If you cannot create a repository, please request this privilege.

GitHub repository

A new repository for your extension is required to store both the source code and the extension documentation. To create one:

  • Access the CAST Extend organization on GitHub.
  • Inside the organisation, create a new repository (as shown in the screenshot below):

  • Fill in the required details for the repository:
    • Use the extension's "ID" for the Repository name, i.e. com.castsoftware.uc.nameoftheextension as explained in Prerequisites and top-tips for creating a custom extension
    • Set the repository to public
    • Tick the Initialize this repository with a README option
    • Choose a license - we recommend the GNU Lesser General Public License v3.0 (this can be created later if necessary, see License).
    • Click the Create repository button

License

A license is mandatory. CAST recommends that you use the GNU Lesser General Public License v3.0 - this can be created at the same time as you create the new repository (see above), or after:

  • In GitHub, navigate to the main page of the newly created repository.
  • Click the Create new file button:

Click to enlarge:

  • In the file name field, type LICENSE or LICENSE.md (in caps) and then to the right of the file name field, click Choose a license template:

Click to enlarge:

  • In the new page that is displayed, choose the GNU Lesser General Public License v3.0 option, then Review and submit:

Click to enlarge:

  • At the bottom of the page, below the commit message fields, commit the license to the master branch, then click Commit new file:

Click to enlarge:

Source code and documentation should be uploaded to the GitHub repository

Source code and documentation for the extension should be uploaded to the GitHub repository:

Source code

Documentation

See How to publish documentation for CAST User Community extensions.

Manage ID ranges for custom extensions

When creating custom extensions that create objects to be saved in the CAST Analysis Service schema or use custom Quality Rules you will need to manage the range of IDs that you assign to these items.  See Managing ID ranges for custom extensions.

Create your extension's description file

Each custom extension must contain a description file that contains the information required for each extension to function correctly. See the following for more information:

Configuring an icon for your extension

When you upload an extension, you can optionally configure an icon to represent your extension in the CAST Extend website, or in the CAST Extension Downloader. See Configuring an icon for your extension for more information.

Auto-distributing specific CAST AIP configuration files with a custom extension

When creating a custom extension, whether using the CAST AIP Extension SDK or with the Universal Analyzer framework, it is possible (since CAST AIP 8.3.3) to auto distribute specific CAST AIP configuration files with the extension. These configuration files will be automatically installed when the extension is installed and will be taken into account when required. See Auto-distributing specific CAST AIP configuration files with a custom extension for more information.

Avoid hard coding CAST Storage Service operator and guest user names in SQL scripts

If your custom extension requires SQL scripts, you should avoid hard coding the CAST Storage Service "operator" and "guest" user names. Some instances of CAST Storage Service may not automatically contain these users, therefore you risk errors during deployment or upgrade.