One of the most powerful features found within the Cloud Elements integration platform is our Elements. As complete, pre-built cloud integrations in themselves, Elements have all the goods ready to go to realize your integration use cases without all the complexity and fuss.
We also include tooling to make it simpler to create new or modify existing Elements, i.e. our Element Builder.
Until now, you had to start from scratch when creating a new Element, unless of course, you have a few of them laying around from earlier builds as I do. While our documentation is great and there are plenty of instructional videos for how to build an Element from scratch, our customers were asking us, “Is there a place where I can go to find examples and contribute to a community of example Elements?”
Yes, there is!
We’ve created an Elements GitHub repo as a way for community members to share Elements:https://github.com/CloudElementsOpenLabs/elements
After importing/exporting the Element, Community Members are able to enhance the Element to suit their individual use cases and, if they want, can give back the additions they have made to the Community for others to share.
Before I get into the How2, let's cover the rules, disclaimers, tips, and tricks so that we can ensure a great experience for everyone.
- Thanks to you in advance for contributing - your fellow and future Community Members appreciate you!
- Cloud Elements provides this repo with the understanding that Cloud Elements does not maintain the integrity of the code for the Elements herein.
- If endpoints change, these Elements and changes are not necessarily known, monitored, or supported by Cloud Elements.
- Cloud Elements also does not guarantee the stability or usability of these Elements.
- Community Members should not add anything to this repo they do not want to be publicly shared.
If you would like to contribute to the community Elements github repo:
- Fork and Clone the repo
- Make a new branch
- Add or update the code you are contributing (please note: if it is a new Element, see Basic Element standards below)
- Push your branch back to the repo and make a pull request
In addition to the file containing the Element JSON, we ask that you:
- Include a short README.md file with a description of what you built (endpoint name and resources available so people can see them without importing the Element)
- A link to the documentation you used when creating the Element
- Any known endpoint limitations or nuances that might affect how your Element works
For your own security, please make sure to remove any API keys and secrets or hard-coded personal data prior to uploading Elements. In the event that you accidentally leave these in the Element, your PR will be rejected. Keep in mind that even if you remove these on a later commit unless you hard-delete your previous commit, these are forever stored in Git and hackers can obtain them.
If you would like to use the Elements in the repo:
- Either Clone the repo or simply grab the JSON using the Raw tab for the example Element
- In the Cloud Elements UI: under Elements, click the Build a new element button
- Select Import
- Navigate to the cloned folder and to the file of the Element JSON you are interested in using
Basic Element Standards:
While we are happy to provide a central place for developers to contribute and share and we welcome a wide array of contributions, we do need to set a basic standard for Element contributions in order to set proper expectations. If your Element does not meet these and you are interested in getting it working so you can contribute, please consider reaching out to firstname.lastname@example.org - we are happy to help you get your Element up to standard prior to contributing!
Contributed Elements should include at a minimum:
- Working authentication
- At least 1 working resource
We encourage you to include but your Element is not required to have:
- Querying via where parameter
- Paging via page, pageSize query parameters
- Refresh authorization
Please see our Element builder documentation: https://docs.cloud-elements.com/home/element-builder-overview
Enjoy and Happy Element Sharing!!