diff --git a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/migrate-organization-versions.md b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/migrate-organization-versions.md index 618723ce..cdcbae48 100644 --- a/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/migrate-organization-versions.md +++ b/docs/administrator-documentation/moderne-platform/how-to-guides/agent-configuration/migrate-organization-versions.md @@ -1,124 +1,50 @@ --- -sidebar_label: Migrating to the latest Organization Service -description: How to migrate from an your Organization service to the latest released version. +sidebar_label: Upgrading to the latest Organization service +description: How to upgrade your Organization service to the latest released version. --- -# Organization Service Migration +# How to upgrade your Organization service to the latest released version -Sometimes changes are made to the Organization service contract. This guide will help you understand what has changed and how to update your Organization service to match the new contract. -This guide highlights changes required when upgrading from to the February 2025 contract changes. +As we continue to expand the functionality of the Organization service, the API contract is also updated. When that happens, you will need to update your own service to match the new contract. -## What has changed? -Four REST endpoints have been added to the organization service. If you are using the organization template you can use [this example controller to implement them](https://github.com/moderneinc/moderne-organizations/blob/fbc92af9e31076c6dea95499517f7f4e53fdc33c/src/main/java/io/moderne/organizations/OrganizationController.java). +This guide will walk you through everything you need to know about performing this upgrade. -GET `/organizations` -- Returns: The contents of `repos.csv` +:::tip +Rather than redoing your Organizations service to match the new contract, you should consider [migrating to a file-based organizational config](./migrate-from-an-organization-service-files-on-the-agent.md) instead as it is much simpler and requires less overhead. +::: -GET `/commit-options` -- Returns: The contents of `commitOptions.txt` +## February 2025 contract changes -GET `/id-mapping` -- Returns: The contents of `id-mapping.txt` +Four new REST endpoints have been added to the organization service that you will need to implement. Implementation details for these can be found [at the bottom of this doc](#implementation-details). -POST `/devcenters` -- Body parameters: `{List organizationIds}` -- Returns: -```json -[ - { - "devCenter": { - "upgradesAndMigrations": [ - { - "title": "Spring boot", - "measures": [ - { - "name": "Major", - "recipe": { - "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", - "options": [ - { - "name": "groupIdPattern", - "value": "org.springframework.boot" - }, - { - "name": "artifactIdPattern", - "value": "spring-boot" - }, - { - "name": "version", - "value": "1-2.999" - } - ] - } - }, - { - "name": "Minor", - "recipe": { - "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", - "options": [ - { - "name": "groupIdPattern", - "value": "org.springframework.boot" - }, - { - "name": "artifactIdPattern", - "value": "spring-boot" - }, - { - "name": "version", - "value": "3-3.2.999" - } - ] - } - } - ], - "fix": { - "recipeId": "org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2" - } - } - ], - "visualizations": [ - { - "visualizationId": "io.moderne.DependencyUsageViolin" - } - ], - "security": [ - { - "recipeId": "org.openrewrite.java.security.OwaspA01" - } - ] - }, - "organizations": [ - "myOrganizationId" - ] - } -] -``` -For a more [detailed example view this example](https://github.com/moderneinc/moderne-organizations/blob/fbc92af9e31076c6dea95499517f7f4e53fdc33c/src/main/resources/devcenter.json#L3). +* **GET** `/organizations` +* **GET** `/commit-options` +* **GET** `/id-mapping` +* **POST** `/devcenters` + * **Body paramaters**: `{List organizationIds}` ## Motivation -There are 2 motivations for this change. The first was to decrease the number of calls which are being made to the Organization service -when retrieving the organization's details. We are moving from a previously paged graphQL endpoint to 4 REST endpoints. -For customers with a large number of organizations, we were seeing performance issues when retrieving the organization details -due to the number of requests being made. +There were two main motivations for these changes: -The second was to allow customers who don’t have custom logic on their Organization to provided the required files on their agent. -For customers who are looking to migrate off of their existing Organization service, [follow these instructions](migrate-from-an-organization-service-files-on-the-agent.md). +1. Customers with a large number of organizations were seeing significant performance issues and timeouts when trying to retrieve the organization details due to the number of requests being made. +2. We wanted to add an easier option for people to configure organizational structure and found that adding REST endpoints that returned files was the simplest and most efficient approach. -## Adding the next REST endpoints to your Organization service +## Implementation details -To implement these endpoints you can use [this example controller](https://github.com/moderneinc/moderne-organizations/blob/fbc92af9e31076c6dea95499517f7f4e53fdc33c/src/main/java/io/moderne/organizations/OrganizationController.java). +If you already have files like `repos.csv`, `commitOptions.txt`, and `id-mapping.txt`, we'd recommend that you emulate [our example controller](https://github.com/moderneinc/moderne-organizations/blob/fbc92af9e31076c6dea95499517f7f4e53fdc33c/src/main/java/io/moderne/organizations/OrganizationController.java) to create REST endpoints that return those files. -For customers who generate the data returned by the graphQL endpoint through other means than reading from the mentioned files, -there could be a couple of changes which are required. As some of these endpoints return the content of some optional files it first imports -to identify if the required endpoint has data to return or can return the contents of an “empty” file. +If you, instead, generate this information via some other means, then you'll need to ensure that the new endpoints return the expected data. -### Adding GET /organizations +Below we'll walk through each of the new endpoints and clarify what they return and what is expected. -Returns: The contents of `repos.csv` -This endpoint returns the content of a CSV file that follows this format of: clone URL, branch, and then a list of one or more organizations – with each column being named org + a number (e.g., org1, org2). Each row represents a repository and its associated organization tree. If a repositories is included in multiple organizations it will have multiple entries in the file. -For example: +### GET `/organizations` + +This endpoint defines your organizational structure. It needs to return the contents of a CSV file that follows this format of: `cloneUrl`, `branch`, and then a list of one or more organizations – with each column being named org + a number (e.g., `org1`, `org2`). + +The organization on the left is a child of the organization on its right. If a repository is included in multiple organizations, it will have multiple entries in the file. + +Below you can see an example of what this endpoint might return: ```text cloneUrl,branch,org1,org2,org3,org4,org5,org6,org7,org8,org9,org10 @@ -128,56 +54,189 @@ https://github.com/Netflix/CassJMeter,master,Netflix,Netflix + Spring,Netflix + https://github.com/Netflix/EVCache,master,Netflix,Netflix + Spring,Netflix + Spring + Apache,Open Source,ALL ``` -### Adding GET /commit-options +### GET `/commit-options` -Returns: The contents of `commitOptions.txt` -This is an optional file which allows you to configure custom commit options for an individual organization. By commit options, we mean the various ways that code can be committed such as only allowing pull requests for code changes –– or allowing people to commit directly to main. +This endpoint allows you to configure custom commit options for individual organizations. By commit options, we mean the various ways that code can be committed such as only allowing pull requests for code changes –– or allowing people to commit directory to main. -If you don’t require this customization return an empty string. +**If you don’t require this level of customization, please return an empty string.** + +This endpoint should return the content of a file where each line begins with an `OrganizationId`, then an `=` sign, then a list of commit options for that organization. You should only include an organization if it differs from your default commit options. + +Below you can find an example of what this endpoint might return: -To configure this endpoint returns the equivalent of the content of a file where each line is `Organization_ID=Application_Commit_Options_seperated_by_comma`. Only include organizations which are different from your defaults -For example: ```text Open Source=Branch,PullRequest Default=Branch,Direct,PullRequest ``` -### Adding GET /id-mapping +### GET `/id-mapping` -Returns: The contents of `id-mapping.txt` -If your organization IDs are the same are your organization names, you do not require this. +This endpoint allows you to configure multiple organizations to have the same name. +If your existing organization Ids are the same as your organization names, you do not need this functionality – so please **return an empty string**. -If you don’t require this customization return an empty string. +If you do need this functionality, then this endpoint should return the content of a file where each line is an `OrganizationId`, then an `=` sign, and then a name that organization should have. + +Below you can find an example of what this endpoint might return: -To configure this endpoint returns the equivalent of the content of a file where each line is `Organization_ID=Organization_Name`. Only include organizations which are different from your defaults -For example: ```text Open Source=OS Default=Default Organization ``` -### Adding POST /devcenters +### POST `/devcenters` -Returns: A list of DevCenters associated with the organizations they apply -```json -[ - { - "devCenter": { - "upgradesAndMigrations": [], - "visualizations": [], - "security": [] - }, - "organizations": [ - "myOrganizationId", - "myOrganizationId2" - ] - } -] -``` +This endpoint allows you to configure [DevCenters](../dev-center.md) for specific organizations. +**If you do not intend to use this feature, please return an empty list from this function.** -If you are using a customer devCenter you will need this if not it can return an empty list. +If you want to use this feature, then this endpoint should take in a list of `OrganizationId` Strings and return a [JSON-like structure of DevCenter configurations](https://github.com/moderneinc/moderne-organizations/blob/main/src/main/resources/schema/organizations.graphqls#L131-L150) and the organizations they apply to. +For example, if someone calls this endpoint with the following strings: `Default, Open Source`, then this endpoint should return DevCenter configurations for those `OrganizationIds`. -You should have some logic to provide the devCenter object related to an organization. You will need return a list of objects which contain the devCenter and a list of the organizations IDs associated with it. +
+ + Below is an example of what might be returned: + + + ```json + [ + { + "devCenter": { + "upgradesAndMigrations": [ + { + "title": "Spring boot", + "measures": [ + { + "name": "Major", + "recipe": { + "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", + "options": [ + { + "name": "groupIdPattern", + "value": "org.springframework.boot" + }, + { + "name": "artifactIdPattern", + "value": "spring-boot" + }, + { + "name": "version", + "value": "1-2.999" + } + ] + } + }, + { + "name": "Minor", + "recipe": { + "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", + "options": [ + { + "name": "groupIdPattern", + "value": "org.springframework.boot" + }, + { + "name": "artifactIdPattern", + "value": "spring-boot" + }, + { + "name": "version", + "value": "3-3.2.999" + } + ] + } + } + ], + "fix": { + "recipeId": "org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2" + } + } + ], + "visualizations": [ + { + "visualizationId": "io.moderne.DependencyUsageViolin" + } + ], + "security": [ + { + "recipeId": "org.openrewrite.java.security.OwaspA01" + } + ] + }, + "organizations": [ + "Default", "Gradle", "Spring" + ] + }, + { + "devCenter": { + "upgradesAndMigrations": [ + { + "title": "Spring boot", + "measures": [ + { + "name": "Major", + "recipe": { + "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", + "options": [ + { + "name": "groupIdPattern", + "value": "org.springframework.boot" + }, + { + "name": "artifactIdPattern", + "value": "spring-boot" + }, + { + "name": "version", + "value": "1-2.999" + } + ] + } + }, + { + "name": "Minor", + "recipe": { + "recipeId": "org.openrewrite.java.dependencies.search.FindMinimumDependencyVersion", + "options": [ + { + "name": "groupIdPattern", + "value": "org.springframework.boot" + }, + { + "name": "artifactIdPattern", + "value": "spring-boot" + }, + { + "name": "version", + "value": "3-3.2.999" + } + ] + } + } + ], + "fix": { + "recipeId": "org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2" + } + } + ], + "visualizations": [ + { + "visualizationId": "io.moderne.DependencyUsageViolin" + } + ], + "security": [ + { + "recipeId": "org.openrewrite.java.security.OwaspA01" + } + ] + }, + "organizations": [ + "Open Source" + ] + }, + ] + ``` +
+ +For a more detailed example of this file, check out [our example in the moderne-organizations repository](https://github.com/moderneinc/moderne-organizations/blob/fbc92af9e31076c6dea95499517f7f4e53fdc33c/src/main/resources/devcenter.json). You might also find it beneficial to read [our guide on configuring the DevCenter](../dev-center.md). \ No newline at end of file