Business Service

Collectively business services define and support the processing of nearly all functionality available within a Verne application. A single business service (or just service) defines a single piece of functionality available to perform on (or create) some long-living registry data.

Examples of a business service relating to companies would be a company registration, maintaining directors, changing addresses, performing an annual return, doing a correction, etc.

Terminology

Somewhat confusingly, within Verne the term business service has the two meanings mentioned below. Whilst each has their own formal definition to distinguish them, both tend to be referred to by the more generic term business service (or just service) so it may be necessary to clarify the context if need be:

Sometimes the ‘business’ is dropped and a ‘business service’ is simply referred to as a service.

• Service instance – The overarching notion or concept of a specific instance of a business service
• Business service configuration/XML – The static XML configuration of a business service

Related Concepts

This section outlines some concepts closely related to the concept of business services and how they drive functionality within Verne.

As a brief overview, when a user or the system starts a new business service the request will reference business service configuration (via the business service code). The request will result in a new service instance being created in the form of a new service transaction.

The following statements also attempt to summarise how the concepts outlined within this page fit together:

• The life of registry data is represented by one or more service instances
• A service instance is represented by one or more service transactions
• A service transaction is a specific action against a service instance. This action will be either creating a new instance or changing the details of the instance. Exactly one service transaction will contain the details (and data) relating to the current, active state of the service instance

See the sections below for more details relating to these concepts, and the example section at the end of this page for a more in-depth, step-by-step example highlighting the life-cycle and interaction of the concepts.

A Service Instance is an abstract concept, and there is no concrete representation in Verne – Catalyst Cloud. A service is represented by 1 or more related service transaction(s).

Registry Data

Registry data is a generic term for any first-level data within a registry application. It could be used to refer to the data within the registry application collectively, but more often it relates to a single instance of some first-level, which may change over time. Registry data relates to both:

• Registry business data (or entity) – such as a company, business name, reserved name, professional etc.
• Non-business registry data – such as a security user, security group, payment basket, payment account, business calendar, search request, workflow task, etc.

Sometimes registry data is referred to by the generic term “entity”, especially when referring to registry business data.

A registration service of some kind will usually be used to create registry data (although it could also be added to persistent storage via migration, data seeding or some other script or procedure). Once added, registry data can be maintained, corrected, ceased in some way, restored, etc. Registry data is therefore long-living in that it can extend beyond a single service instance.

Registry domain data is stored in the service transaction domainTree, although registry data in its entirety consists of all of the following service transaction properties:

• domainTree (the domain data)
• rootDomainName
• identifier
• businessIdentifier
• businessName

Registry data is always copied to a new service transaction when it is created if it is based on another service transaction. This is regardless of whether it’s for the same service instance or not. See the life cycle concept for more details around multiple service transactions for the same instance and service transactions relating to different service instances.

Authority data relating to who has authority or access to the registry data or entity is also contained within the domainTree since it is long-living and survives across service instances.

Domain Tree JSON – Registry Data

"domainTree" : {
    "_id" : "300e67edccf805b0",
    "name" : "Hero",
    "attributes" : {
      "CostumeYn" : "Y",
      "RegistrationDate" : "2020-05-20T17:34:33.524+0000",
      "Name" : "Batman",
      "YearOfArrival" : "1974",
      "CapeYn" : "Y",
      "SuperPowers" : "agility,fighting"
    },
    "authority" : {
      "_id" : "2408c55758ffb143",
      "name" : "AuthorityInstance",
      "objName" : "authority",
      "attributes" : {
        "CreatedDate" : "2020-05-20T17:34:32.834+0000",
        "CreatedByRequestId" : "975f368444eb9af9b57cb9fb78e1206c",
        "CreatedByUser" : "1a87b82c3129bfb9b30944c9182f45efc22b097b09a1b6789a7099fb8512d63c",
        "CreatedByUserName" : "External User"
      },
      "authorities" : [
        {
          "_id" : "4420c8c1e2795b85",
          "name" : "Authority",
          "arrName" : "authorities",
          "attributes" : {
            "CreatedDate" : "2020-05-20T17:34:32.834+0000",
            "CreatedByRequestId" : "975f368444eb9af9b57cb9fb78e1206c",
            "CreatedByUser" : "1a87b82c3129bfb9b30944c9182f45efc22b097b09a1b6789a7099fb8512d63c",
            "CreatedByUserName" : "External User",
            "Type" : "initiator",
            "Status" : "active",
            "GrantMechanism" : "registration",
            "GrantedOn" : "2020-05-20T17:34:32.834+0000",
            "UserType" : "individual",
            "UserIdentifier" : "1a87b82c3129bfb9b30944c9182f45efc22b097b09a1b6789a7099fb8512d63c",
            "UserFullName" : "External User",
            "FirstName" : "External",
            "LastName" : "User"
          }
        }
      ]
    }
  },

Business Service (configuration)

The static XML configuration relating to a business service is also referred to as a business service. See business service configuration for more details, but importantly each business service refers to a form which configures what data structure is available for that business service’s view tree.

Service Instance

A service instance is an abstract concept. A service instance refers to a specific incarnation (instance) of a business service based on some business service configuration and is represented by one or more service transactions.

A service instance is an abstract term referring a runtime instance of a configured business service and the service transaction(s) created and updated during the processing of that configured business service.

Whilst registry data is long-living, a service instance has a shorter life (although it could still span days, weeks or even longer depending on how the business service is configured) but again, can generally be thought of as a specific action against the registry data. A service instance is a specific business service called against specific registry data. In other words, maintain directors is a business service, but you could maintain directors of a company many times and each of these times would be an instance or service instance of that business service.

One or more service transactions can be involved in the processing of a service instance.

Service instance domain data is stored in the service transaction serviceTree, although service instance data in its entirety (not just domain) consists of all service transaction properties other than the ones mentioned in the registry data section above and ones relating to the "last updated" values e.g. updatedBy, updatedByUser, etc.

Service instance data is not copied when a new service instance is created based off existing data. For example, a new maintain business service (a new service instance) is started based on registered/activated registry data (a previously activated service instance). However, service instance data is copied to a new service transaction when it is created based on a service transaction for the same service instance e.g. the user selects a saved service instance from their dashboard to make further changes. See the life cycle concept for more details around multiple service transactions for the same instance and service transactions relating to different service instances.

Service Transaction

Service transactions are intrinsically tied to business services, service instances and registry data as they contain the information relating to both the service instance and registry data.

Service transaction(s) are the concrete representation of an abstract service instance.

See the service transaction concept and also the life cycle concept for more information around the context of a business service, the link between business services and service transactions and service transaction states.

In relation to service transactions a service instance refers to all service transactions collectively that relate to that service instance (if more than one). The service transaction that is the current tip (for non-activated service instances) or the current head (if activated) equates to "the" service instance in its current state.

Form and Service Form

If a business service can be thought of as what functionality you can perform, then the form can be thought of as what data the action is performed against. The service form is a form resolved against a specific business service configuration that references it. It is also closely linked to the view tree.

Life Cycle

The life cycle concept is closely tied to the business service concept as it is the system by which service instances and the service transactions that relate to them are managed, and would be an excellent next step if you are not already familiar with its content.

Registration Service

A registration service is a shortcut term used to refer to a service instance relating to a business service that has a mode of Create. Such a service is used to create new registry data which becomes live on the register if it is activated. Also see the maintain service term below.

A registration service is used to create new registry data.

Maintain Service

Similar to a registration service above, a maintain service is a shortcut term used to refer to a service instance relating to a business service that has a mode of Change. Such a service is used to maintain registry data that is already live on the register. If activated a maintain service becomes the new version of registry data that is live on the register, having amended the previous version on which it was based.

Maintain services are typically performed to reflect some change in the real world which needs to be represented on the register. For example an address changes, or the name of a company or the appointment of one or more of it’s shareholders or directors, etc. As such the maintain service does not mean the previous version of the registry data that was live on the register is not still valid for that time – it is valid, but has simply changed which now needs to be reflected. Maintain services can only ever be used to make changes to the current live version on the register.

Also see corrections and how they differ from maintain services.

A maintain service is used to update existing registry data to reflect real-world changes over time.

Example

The following example attempts to highlight the differences between the above concepts: business services, registry data, service instances and service transactions.

In the above example, two service instances were started and activated, each using a different business service. The first registration instance made use of two service transactions, whereas the second maintain address instance used just one service transaction. For both instances there was only one conceptual instance of entity data.

See the life cycle example which is more complex and also from the context of highlighting the life cycle management process rather than just the business service concepts.

Abstract Business Services

Abstract business services are used to conditionally switch easily between business services based on some attributes. A very basic example is the View Company service, that can be either a View Local Company or a View an Overseas Company.