Service revisions

Learn the concept and steps for service revisions.

Introduction

With Uniscale, you can create revisions for each service, allowing you to compare revisions and get a historical overview of changes. Furthermore, your revisions will have their own approval flow.

Service editor: Changelog

In this article, we will explore two areas:

• How to: Service revisions: Learn how to utilize this functionality.

• Concept: Service revision: Understand the concept behind revisions.

How to: Service revisions

Service locking and approving

You will lock and approve each service revision as you want to keep track of your changes over time.

Service editor: Ready and approve revision

1. Select "Ready all"

2. In the overview, select "Set all to ready"

3. Select "Approve"

   1. Give your revision a title. Note that it will automatically get a version number.

   2. Optional: Add a description.

   3. Click "Submit"

Once you have approved a revision, you can head to the SDK Portal to generate an updated SDK: Generating the SDK

Create a new revision

Service editor: Start new revision

To start a new revision:

1. Click "Start new revision"

2. Give your revision a title. Note that it will automatically get a version number.

3. Optional: Add a description.

4. Click "Submit"

Service changelog

To view the changelog, click the "clock" icon in the upper right corner.

Service editor: Changelog

You can select and compare each of your revisions and get an overview of all changes.

Each color will represent the type of change:

• Green: Added

• Purple: Modified

• Red: Deleted

Explore previous revisions

To explore each of your previous service revisions, click on the name of your revision in the upper right corner.

Service editor: Previous revisions

---

Concept: Service revision

Within the cycles of modeling and producing well-written documentation, you will find yourself completing items and getting them to a stage where you can lock things in place before a revision.

To do so in a better manner, we have provided each item in your documentation with its lifecycle related to its meaning.

For that, we distinguish between:

• Items to be reused (endpoints, data contracts, properties).

• items that are single declarations (namespaces, Use case flows, Technical use cases)

Listing the structure of a service, we can have the following items:

• namespaces

• technical use cases

• use case flows

• endpoints

• data contracts

  • aggregates

  • value objects

  • property groups

  • properties

For a more detailed breakdown, read Service basics

Each item is subjected to a lifecycle, with different meanings.

Completion cycle

Endpoints, data contracts, and properties are considered items that are agnostic of the entire status of the service. As a whole, they can be "completed" before the overall approval status and as such, their cycle reflects their state of being "done" or "completed".

Exploring step by step the process, we have:

• When a new item is created, it is in the status of "draft"

• Afterward, with new changes done, it goes into "edited"

• Once all the conditions are met, the item can be "completed"

• Once completed, the item can be "opened" to new changes

• If some changes are made, then the item is moved back into "Edited"

Lockable cycle

Namespaces, technical use case flows, and use case flows are all process items that are relevant to the end goal of the service. As such, rather than a completion intention, they have a "is this final", or "is this locked" cycle.

Exploring step by step the process, we have:

• When a new item is created, it has the status of "edited"

• Once all requirements are met, it can now be "marked as ready"

• When the owning module is Approved, all items are moved to "locked"

• Later, when a new revision is made, all items are still in "locked"

• From here, one can manually "unlock" the items that are intended for changes, and move them to "unlocked"

• If any change is made to a "unlocked" item, it gets automatically moved to the status "edited"

Approval of the service & revisions

Service approval is a collation of all the above processes and loops. Let's take a conceptual example of that scenario, with images to visually represent the state at all times.

1. In the start, the service grows to a stage where various items will be in either the "locking lane" or the "completion lane" . This is further expanded with dependencies between the 2 types, in our example in a simple, upwards dependencies manner.

2. As things progress in the service modeling, all items are now completed and the process items are ready to be locked.

3. With everything in place, the service has now been approved, and Revision 1.0 has been created. This means all items are moved to locked state and the others remain completed.

4. From here on, of course, the service will grow towards a new revision, and to initiate one, the service will need to be opened, and various items will be unlocked. As such, all items that are downward dependencies of such items will be marked as Opened, marking the intent to add changes. Once changes are made, the cycle goes back to step 1 in this guide.

Service timeline

Over time the service will receive many revisions, all needed incremental changes. This is expected and is a sign of an ever-growing service (in quality and overview of usage, and not primarily in size).