Service Settings

Service State

As Consumers begin using a Service, it may not be possible to decommission that Service immediately. Instead, it might be necessary to first decommission its Service Items and then, if no Consumers remain, peacefully decommission the Service itself. To facilitate this process, NetOrca provides different states for Services, allowing Service Owners to manage the lifecycle of a Service effectively.

The following are the available states for a Service:

State	Description
IN_SERVICE	This is the default state for a Service. When a Service is in this state, it is fully available. Consumers can create new Service Items, modify, or delete existing ones
NO_NEW_SERVICE_ITEM	In this state, the Service is no longer accepting new Service Items. However, Consumers can still modify or delete existing Service Items that were created before the Service entered this state.
NO_MODIFY_EXISTING_SERVICE_ITEM	When a Service is in this state, Consumers can only decommission their Service Items
DECOMMISSIONED	The Service has been fully decommissioned ano no loger available to the Consumers

Service Owners can change the state of their Services using the following code:

HTTP requestPython SDKGUI

PUT or PATCH /v1/serviceowner/services/<service_id>/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "state": "<one of the states from table above>"
}

Service Visibility

Services can be either public or private. When a Service is made private, only specific Consumers can create new Service Items. To restrict access to certain Consumers, the Service Owner must add the relevant Consumer teams to the allowed_teams field, making the Service visible only to those teams. If the allowed_teams list of a Service is left empty, the Service remains accessible to everyone.

Once a Service is set to private, submissions with new Service Items from that Service will be rejected from Consumers not included in the allowed_teams list. However, existing Service Item Consumers who are not part of the allowed teams will still be able to submit to generate only MODIFY and DELETE Change Instances.

The Consumers can be added or removed from allowed_teams list by updating Service settings using an HTTP PUT or PATCH request to /serviceowner/services/<service_id>/ endpoint:

HTTP requestPython SDKGUI

PUT or PATCH /v1/serviceowner/services/<service_id>/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "allowed_teams": [<consumer_team_id>, <consumer_team_id>, ...]
}

Approval Required

By default, the initial state of a Change Instance is set to PENDING. The Service Owner can then perform pre-validation before executing the changes. If the pre-validation is successful, the state is updated to APPROVED, and after successfully applying the Change Instance, the state is further updated to COMPLETED.

For some Services, pre-validation is unnecessary, so the Change Instance's state can be set to APPROVED immediately after it is generated, bypassing the PENDING state.

Each Service has an approval_required field. If this field is set to True, the initial state of its Change Instances will be PENDING. If set to False, the initial state will be APPROVED.

Service Owners can define the state in two ways:

• Through an endpoint or GUI

HTTP requestPython SDKGUI

PUT or PATCH /v1/serviceowner/services/<service_id>/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "approval_required": false
}

• By updating the JSON Schema: The key value must be located in the JSON Schema's metadata:

      "metadata": {
          "approval_required": false
      },
  

Allow Manual Approval and Completion

You can restrict the approval and completion of Change Instances so that they can only be done via an API key, rather than through an endpoint or GUI. Two fields, allow_manual_approval and allow_manual_completion, are defined for Services to manage these settings.

To update these settings:

HTTP requestPython SDKGUI

PUT or PATCH /v1/serviceowner/services/<service_id>/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "allow_manual_approval": true,
    "allow_manual_completion": false
}

Minimum Schema Version

As more Service Items are created, maintaining the consistency of the Service Schema becomes increasingly important. There may be scenarios where a Service Owner has hundreds of valid Service Items associated with their Service and needs to introduce a new mandatory field for all future Service Item requests. Simply updating the Schema to include the new required field would result in all existing Service Items being marked as invalid in the future submissions, as they would lack this field. To avoid this, Service Owners typically want the new Schema to apply only to new Service Items, while the existing Service Items remain valid under the previous Schema.

To address this issue, NetOrca propose minimum Schema version that allows Service Owners to update their Service Schemas incrementally while maintaining compatibility with older versions. This approach enables Service Owners to introduce new Schemas as needed, with the flexibility to phase out older Schemas gradually as Consumers update their Service Item declarations to comply with the new Schema.

Each Service Schema will have a version number, starting from 1, that increments with each update. This allows the users to distinguish between different versions of the Schema and apply them accordingly. If the minimum Schema version is not defined, i.e. the latest, all new and existing Service Items will be validated against the latest version of Service Schema. However, if the minimum Schema version is NOT the latest,

• Any new Service Items must be validated against the latest Schema version
• Existing Service Items will be validated against, first, the latest, and then, the minimum Schema version.

To define the minimum Schema version:

HTTP requestPython SDKGUI

PUT or PATCH /v1/serviceowner/services/<service_id>/ HTTP/1.1
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
    "minimum_version": <older version number>
}