Leverage Native Integrations of Your Devices in Symphony
- Experience with Java programming and multithreading
- Experienced in GitHub and GitFlow process
- Any Java IDE (recommended products are Eclipse or IntelliJ)
Before writing your first adapter
- View the Symphony Product Catalog and determine if an adapter already exists for the device.
- Familiarize yourself with the samples in https://github.com/AVISymphonyDev/samples.
- Obtain a Version Control System (VCS repository for GitHub) either by:
- Utilizing your own repository, where you own the source code of your adapter entirely and your partnership/support with AVISPL is limited. OR-
- Requesting a repository in AVISPL’s account (request process below), where an MIT license is applied, (e.g., https://github.com/AVISPL/dal-avdevices-power-middleatlantic/blob/master/LICENSE). With this option, you have AVISPL’s full support of the adapter and faster adapter reviews and approvals, (see Testing Your Adapter section). This type of repository has certain limitations and rules applied such as:
- Master branch is protected from any commits outside of the GitHub pull-requests,
- Pull requests require at least one (1) review from the AVISPL staff before merging into the repository,
- GitFlow branching approach is required: see https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.
Writing your first adapter
- Ensure you are using the correct communicator type which depends on the communication protocol available on the target device. If the device supports multiple protocols, you can choose (e.g., Shell, Telnet, HTTP, etc.). For more information, please see https://marketplace.avisplsymphony.com/documentation#dal-java-sdk.
- Be sure to use a correct branching strategy if you’re using AVISPL’s repository:
- Production branch: master
- Develop branch: develop
- Feature branch prefix: feature/
- Release branch prefix: release/
- Hotfix branch prefix: hotfix/
- Make sure you’re following the recommended GitFlow pipeline when using the AVISPL repository:
- develop branch is created from master branch and maintained in parallel with master branch indefinitely.
- feature branches are created from develop branch and merged back when feature is completed.
- release branch is created from develop branch when all features are implemented. release branch is used to prepare for release meaning only bug fixes, documentation changes, etc., reside in release branch, (i.e., no new features).
- After release is tested and approved, release branch is merged to master branch and the master branch is tagged with a release tag. The develop branch is rebased with master branch.
- When necessary, the hotfix branch is created from master branch and contains changes for hot fix only. After tested and approved, the hot fix is merged back into the master branch and master branch is tagged with release tag. The develop branch is rebased with master branch.
- Make sure you’re following recommended development practices including: unit test, static code analysis, etc.
- Be sure to use GitHub actions for Continuous Integration (CI).
- The setup may vary, the required features are:
- Executing tests while building your code on GitHub to enable branch checking mechanisms based on tests/builds.
- Executing static code analyzers, (e.g., maven pmd), to enable branch checking mechanisms based on code style/quality.
- Using upload-artifact github action to have your project artifacts stored/exported within the particular branch/pull-request. See GitHub actions for more information, https://github.com/actions)
Testing your adapter
To test your adapter without publishing, use the Symphony dal-simulator. The required libraries and documentation are available in dal-simulator project under the samples repository.
After testing with dal-simulator, you can try uploading your adapter onto the Symphony platform. To load adapter to Symphony platform:
- Create your account on Symphony Connect.
- Create a device adapter, specify its name, execution class with package, adapter version, the device model for your adapter, attach your jar file and submit for review.
- Wait for AVISPL review/approval.
For faster package review/approval, keep in mind:
- AVISPL internal repository-based adapters are more likely to be reviewed first or to be accepted at all.
- Attaching release notes and pull request/repo paths in the description section on Symphony Connect may shorten the amount of time necessary for review.
After your adapter is reviewed
Check the functionality of your adapter and ensure the adapter suits your needs. Pull the latest changes from develop/master branches, in case you want to update the functionality or apply fixes. Create a new feature branch and repeat the development process described above.Rejected Adapter
Check your email and carefully read the review notes or GitHub comments (for AVISPL repository). Apply necessary fixes and repeat the adapter submission process.