Change Instance Processing

Once Consumers submit their full declaration, Change Instances are generated based on the requested changes. At this point, it becomes the responsibility of the Service Owners to review, process, and implement these changes to ensure that the infrastructure reflects the desired state defined by the Consumers. When a Change Instance is created, the Service Owner must actively take charge of its implementation and execute the necessary backend changes to align the actual service or infrastructure with the declared state. Once the intended state is successfully reflected in the infrastructure, the Change Instances can be safely marked as COMPLETED.

Process Overview Diagram

sequenceDiagram
    participant Consumer
    participant NetOrca
    participant ServiceOwner
    participant Deployment
    Consumer->>NetOrca: New declaration sent
    activate NetOrca
    NetOrca-->>NetOrca: Validation Check
    alt Validation Fails
    NetOrca-->>Consumer: 400 Error
    else Validation Passes
    NetOrca-->>NetOrca: Declaration compared against existing Service Item's
    opt Changes detected
    NetOrca-->>NetOrca: Change Instances created
    end
    NetOrca->>Consumer: 201 OK
    end
    loop Check for changes
        ServiceOwner->>NetOrca: Fetch Change Instances
        alt No changes detected
            NetOrca->>ServiceOwner: No Changes
            Note over ServiceOwner: Do nothing
        else Changes detected
            NetOrca->>ServiceOwner: List of Change Instances
            Note over ServiceOwner: Process Change Instances
            loop For each Change Instance
                ServiceOwner-->>Deployment: Push changes
                activate Deployment
                Note over Deployment: Process changes
                Deployment-->>ServiceOwner: Process finished
                deactivate Deployment
                ServiceOwner-->>NetOrca: Mark Change Instances as COMPLETED
                Note over NetOrca,ServiceOwner: Deployed Items details included in callback
            end 
        end        
    end

Change Instance State

The service owners process the change instances in their infrastructure and then, they will update the state of each change instance. Here is the table of possible states and their meanings:

graph LR
    1[PENDING] --> 2[APPROVED]
    1 --> 3([REJECTED])
    2 --> 4[COMPLETED]
    2 --> 5([ERRORED])
    3 --> 6([CLOSED])
    5 --> 6([CLOSED])

To process a change instance:

POST /v1/orcabase/serviceowner/change_instances/<change_instance_id> HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY> or Token <token>
{
    "state": "APPROVED"
}

Approval Required

In NetOrca, Services can be configured to either require approval or make it optional before execution, depending on the nature of the service and how strict the change validation process needs to be. The PENDING and REJECTED states are considered pre-validation stages, which allow Service Owners to assess whether the requested declaration can be implemented without actually applying any changes to the infrastructure. This pre-validation goes beyond the initial JSON schema validation that occurs during the Consumer’s submission—it gives Service Owners a chance to review the intent and feasibility of the change. However, not all services require this level of manual review. For some Services, approval can be set to optional. The approval setting for each service is explained on the Service Settings page. When approval is required for a service, all generated change instances will start in the PENDING state. They must be explicitly moved to the APPROVED state by a Service Owner before they are eligible to be marked as COMPLETED. Otherwise, the initial state for the Change Instances will be APPROVED.

Detailed Process Diagram

sequenceDiagram
    participant Consumer
    participant NetOrca
    participant ServiceOwner
    participant Deployment

    Consumer->>NetOrca: New declaration sent
    NetOrca-->>NetOrca: Validation and Submission
    Note over NetOrca: Change Instances are generated
    NetOrca->>Consumer: Submission Successful
    ServiceOwner->>NetOrca: Fetch Change Instances
    loop For each Change Instance

        opt Auto Approval disabled
            NetOrca->>ServiceOwner: PENDING Change Instance
            ServiceOwner->>Deployment: Pre Validation

            alt Pre Validation Failed
                ServiceOwner->>NetOrca: mark as REJECTED
            else Pre Validation Passes
                ServiceOwner->>NetOrca: mark as APPROVED
            end
        end

        NetOrca->>ServiceOwner: APPROVED Change Instance
        ServiceOwner->>Deployment: Push declaration

        alt Execution Passes
            Note over Deployment: Process new declaration
            ServiceOwner->>NetOrca: mark as COMPLETED
        else Execution Failed
            ServiceOwner->>NetOrca: mark as ERROR
        end          
    end

Service Item Runtime State

The runtime_state of a Service Item is directly influenced by the state of its associated Change Instance.

Initially, when a Consumer submits a request to create a new Service Item, a CREATE Change instance will be generated, and its runtime_state is set to REQUESTED. This indicates that the request has been received but not yet provisioned. Once the corresponding CREATE Change Instance is either initially generated in the APPROVED state or later updated to APPROVED by a Service Owner, the Service Item's runtime_state transitions to IN_SERVICE. This reflects that the requested service has been approved and is now active or ready to be delivered to the Consumer.

Other Change Instance state transitions do not affect the Service Item's runtime_state. For example, if the state goes to either ERRORED or COMPLETED, the Service Item remains in the IN_SERVICE state—indicating that it is considered active regardless of whether the creation process succeeded fully or encountered issues.

In later submissions, if the Consumer modifies the declaration for this Service Item, MODIFY Change Instances will be generated. MODIFY Change Instances do not affect the runtime_state, which means the Service Item continues to stay as IN_SERVICE throughout the modification process.

Eventually, when the Consumer removes the Service Item from their submission entirely, DELETE Change Instance will be generated. If the DELETE Change Instance is moved to the APPROVED state, the Service Item's runtime_state will transition to DECOMMISSIONED.

sequenceDiagram
    participant ServiceItem
    participant ChangeInstance CREATE


    Note over ChangeInstance CREATE: PENDING
    Note over ServiceItem: REQUESTED
    Note over ChangeInstance CREATE: APPROVED
    ChangeInstance CREATE->>ServiceItem:  
    Note over ServiceItem: IN_SERVICE
    activate ServiceItem
    Note over ChangeInstance CREATE: COMPLETED


    participant ChangeInstance MODIFY
    Note over ChangeInstance MODIFY: PENDING
    Note over ChangeInstance MODIFY: APPROVED
    Note over ChangeInstance MODIFY: COMPLETED


    participant ChangeInstance DELETE
    Note over ChangeInstance DELETE: PENDING
    Note over ChangeInstance DELETE: APPROVED
    ChangeInstance DELETE->>ServiceItem:  
    Note over ServiceItem: DECOMMISSIONED
    deactivate ServiceItem
    Note over ChangeInstance DELETE: COMPLETED

Deployed Item

Deployed Item is an JSON configuration that can be defined by the Service Owner when processing a Change Instance. A Deployed Item typically contains deployment-specific information—such as configuration details, runtime parameters, or output artifacts—that may be helpful or relevant for the Consumer to be aware of. Deployed Items are versioned, meaning each time a new one is defined, typically as part of Change Instance Processing, a new version is incrementally created and stored. Over the lifecycle of a Service Item, multiple Deployed Items can exist, each representing a historical snapshot of how the Service Item was deployed at a specific point in time. To create a Deployed Item for a Service Item along with Change Instance process:

POST /v1/orcabase/serviceowner/change_instances/<change_instance_id> HTTP/1.1
Content-Type: application/json
Authorization: Api-Key <YOUR_API_KEY> or Token <token>
{
    "state": "APPROVED",
    "deployed_item": { ...configuration dictioanry }
}