Prerequisites and top-tips for creating a custom extension

GitHub account

You need a GitHub account to store the custom extension’s source code anddocumentation. 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.

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.

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.nameoftheextensionas 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, thenReview 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:

• Extension description file
• Extension tags

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.