You may find the adapter you are interested in contributing already exists in one of these GitLab groups. Some adapters may fall into multiple categories but from a repository perspective, they can only reside in one group. If you create a new adapter, you will be asked to provide the category you believe that adapter belongs in as well as a link to information on the system the adapter integrates with.
...
...
@@ -17,14 +37,16 @@ You may find the adapter you are interested in contributing already exists in on
Before contributing a new adapter, be sure you have verified there is a need for one.
* Review existing adapters in the category groups above and verify the adapter doesn't already exist.
* Adapters may fall into multiple categories, you must review all of the adapter categories.
* You can go to the [adapter home](https://gitlab.com/itentialopensource/adapters) and search for the adapter using the "Search by name" field to the top right of the list of Subgroups and projects. Adapters names should include vendor and system information, so you should be able to use those in your search.
* You can also go through the existing adapters in the category groups above.
* Remember adapters may fall into multiple categories, so you may need to check in several groups.
* Adapter Builder should inform you if the adapter you are building already exists.
* If the adapter does not exist;
*You may submit your new adapter to the project following the remainder of this process.
*Please submit your new adapter to the project following the remainder of this process.
* The Itential Adapter team will review your adapter and upon acceptance, opensource it.
* If the adapter already exists but is currently insufficient for your needs (e.g it is built on an older version of the API or does not have coverage of the API calls that you need);
* You should submit an issue under the existing adapter following [this process. ](https://gitlab.com/itentialopensource/adapters/adapters-contributing-guide/-/wikis/How-to-Submit-an-issue)
* Please submit an issue following the [How to Submit an Issue](https://gitlab.com/itentialopensource/adapters/adapters-contributing-guide/-/wikis/How-to-Submit-an-issue) process.
* The Itential Adapter team will review the request and determine the best path forward. This may include updating the existing adapter or building a new one.
## Step 2 - Create an Adapter
...
...
@@ -32,17 +54,19 @@ Before contributing a new adapter, be sure you have verified there is a need for
* You may be able to get this from the Vendor website or from contact with the Vendor.
* You may have to convert a WSDL or a Postman Collection to an OpenAPI document using something like APImatic.
2. Build the new adapter using the [Itential Adapter Builder](https://adapters.itential.io).
3. Install the generated adapter into your IAP environment.
3. Install the generated adapter into your IAP environment following the process to install the adapter.
4. Confirm the adapter is available in IAP by creating a service instance of the adapter.
5. In the package.json, under the Keywords section you should add information on categorization. This means adding the one or two words in the category to the list of keywords. This should follow the "Adapter" keyword. You can also verify the Adapter name keywords. Often Vendor and System are combined into one keyword and it may be better to make multiple keywords for these.
6. Also in the package.json, the repository.url and homepage urls are generic. You should add the category to the path after /adapter/ as follows - git@gitlab.com:itentialopensource/adapters/**telemetry-analytics/**adapter-sevone.git. Notice if the category is multiple words, the words should be separated by a -
## Step 3 - GitLab Project Creation
1. Determine what category the new adapter should be in.
2. Go into the GitLab category group folder for the new adapter. (links above)
If you do not have permission to create a project within the Itential Adapter Opensource project;
you will need to submit an Itential Service Desk (ISD) or an Adapter Team (ADAPT) ticket. Make sure to include the name and category of the adapter.
If you do not have permission to create a project within the Itential Adapter Opensource project - the _New project_ button will not appear. In this case you will need the Adapter Team to create the repository. Please return to the [contributing-guide project](https://gitlab.com/itentialopensource/adapters/contributing-guide) and submit an issue for the Adapter Team to create the repository for your adapter. You will need to provide the name and the primary category for the adapter.
If you have permissions within the Itential Adapter Opensource project you can follow this process:
If you have permissions within the Itential Adapter Opensource project you should follow this process:
1. Click the _New project_ button.
2. Choose _Create Blank Project_ button.
...
...
@@ -55,16 +79,17 @@ If you have permissions within the Itential Adapter Opensource project you can f
This assumes you have installed git in your local environment.
The Adapters use a **_master_** branch and not the main branch so please follow these instructions In your environment
The Adapters use a **_master_** branch and NOT the main branch so please follow these instructions In your environment
```bash
1. cd existing_folder where you installed the adapter
3. git remote add origin <link to the repo you created>
4. git add
5. git commit -m"Initial commit"
6. git push -u origin master
```
## Step 5 - Adapter Team Review
You will need to submit an Itential Service Desk (ISD) or an Adapter Team (ADAPT) ticket for the Adapter Team to review the Adapter. Make sure to include a link to the repository in your ticket.
Please submit an issue in your new adapter project, to have the Adapter Team review and opensource your adapter.
