Representing Contracts and License Agreements in Ardoq

This article describes a recommended approach to representing contracts and license agreements in Ardoq. There is not, currently, an Ardoq Use Case Solution for representing contracts and license agreements. The document provides guidance on how to add the Contract component type to existing solutions.

As a minimum, you will have implemented the Application Lifecycle Management Solution, and our recommended approach to including contracts to supply technology products (hardware and/or software) builds on the Technology Portfolio Management Solution. The latter creates your Technology Catalog, which is the natural place to link in contracts to supply technology products. However, it is not a pre-requisite, and the article contains guidance on representing such contracts where you have not adopted a Technology Catalog.

The approach described here is not intended to reproduce all the functionality of a contract and license management system. Rather, it represents a way of including contracts and licenses so that they can form part of the wider knowledge graph and ecosystem that make up Ardoq. It may therefore complement a specialist contract and license management system or provide a minimalist, lightweight approach to managing contracts and licenses. It facilitates the use of Ardoq to address the following questions:

All types of agreements (contracts supplying people or services, license agreements providing software or hardware) are represented with the Contract component type. As there may be many contracts in the workspace, it might be convenient for these to be divided into meaningful categories: the metamodel makes provision for Contract components to be (optionally) children of Category components.

For the remainder of this article, we will use the term “agreement” to represent all these different types. We recommend the following four fields to describe the agreement:

You can add additional fields to provide a more detailed description of your contracts.

We use the Supplies reference type to show the Organization supplying products, services, or resources under the Contract. We recommend that supplying organizations are represented in a separate workspace (the External Organizations Workspace). The consuming party to the contract is linked with a Consumes reference type. This may be your organization as a whole or just one part of your organization. The consuming party may therefore either be an Organization or an Organizational Unit component.

Unless the contract is specific to one part of your organization, we recommend the consuming party should be the Organization component that represents your organization. We recognize that agreements can be completely symmetric, with benefits and obligations for all parties, and that agreements might have more than two parties. Fully symmetric agreements can be represented using just the Consumes reference type from each party. A Refers To reference can also be used to link to other organizations or organizational units that are involved in the Contract (e.g. as delivery partners) but are not, themselves, signatories.

Contract components should also have an owner; the person within your organization that has responsibility for that contract. This is represented in the usual way with an Owns reference from a Person to the Contract. Figure 1 shows the basic metamodel for representing agreements, their parties and owners.

Figure 1 - basic contract metamodel

A common type of agreement is for the supply of technology products, software, and/or hardware. The Technology Portfolio Management Solution provides a technology product catalog used to describe all the technology products in use in your organization, including a link from the supplying organization (e.g. Microsoft (Organization) -> Supplies -> Windows 11 (Technology Product)).

A Supplies reference from a Contract to a Technology Product is used to indicate that the supply of that product falls within the scope of that contract. Of course, one Contract may supply more than one Technology Product. Figure 2 shows the full metamodel for representing agreements for the supply of technology products.

Figure 2 - metamodel for technology product agreements

Note that the Organization that supplies the Technology Product may not be the same organization that supplies the Contract. For example, a major technology provider, such as Microsoft, supplies a product but relies on resellers to contract with its customers. Hence a need for distinct Supplies references from both the technology supplier of the product and from the Contract that “supplies” (licenses) the product.

Figure 3 - reseller contract example

Another common type of agreement is for the supply of data. Our Data Lineage Solution provides for the creation of a logical data catalog that describes an organization’s data assets organized by subject area with component types Data Entity and Subject Area.

In the same way that a Contract component can be associated with the Technology Products it supplies using a Supplies reference, the Data Entities supplied via a Contract can be represented with Supplies references from the Contract to the relevant Data Entity components.

Figure 4 - metamodel for data product agreements

We may also wish to represent contracts that supply resources or services in Ardoq. We can use the Supports reference type to show the reliance of assets on people or services provided via contracts with third-party providers. The following component types can all be the destination of a Contract Supports reference to indicate that they are dependent on people or services provided by the supplier under the terms of that contract:

The full metamodel, covering both the potential supply of technologies and support with people and/or services is shown in Figure 5 below.

Figure 5 - metamodel for the supply of technologies, data, people, and/or services

Many Ardoq customers begin their knowledge graph with a core of essential component types, typically centered around Application, Person, Organizational Unit, and Business Capability. Adoption of a Technology Catalog is strongly recommended where an organization has multiple deployed instances of the same technologies (applications, technology services, servers, data stores).

Without the use of a Technology Catalog in this situation, maintenance of common information associated with the technology, such as vendors, vendor lifecycles, approved standards, and vulnerabilities, will quickly become a nightmare. The Technology Portfolio Management Solution includes the metamodel and assets that comprise the Technology Catalog. The metamodel described here plugs into this approach, linking contracts to the technology products that make up the Technology Catalog.

Organizations that have mostly single deployments of technology components may choose not to create a Technology Catalog but rather rely on the components that represent deployed instances to “double up” as their catalog. This approach can be sustainable as long as there is a predominantly one-to-one mapping of technologies to deployed instances.

If you are following this approach, you will not have the Technology Product component type in your metamodel. You will therefore have to adapt the above metamodel by pointing the Supplies reference from the Contact to the component types that are covered by such product supply contracts and license agreements (e.g. Applications, Technology Services, Servers).

We’ve proposed four possible fields for describing contracts, in addition to the references to and from other components. You may wish to add more fields to reflect the way your organization describes or classifies contracts, and you might be able to automatically populate these from some other systems, such as Procurement or Contract Management systems. For example, you might choose to track Cost To Date (for service contracts that don’t involve fixed regular payments) or to separate Capex and Opex costs.

The relationship between contract costs and an overall IT cost model for your Ardoq knowledge graph is complex and will vary with different types of contracts. There is therefore no generic, simple way to connect the range of possible cost fields in Contracts with the wider IT Cost Management system supported by the IT Cost Management Solution.

You might also want to track the number of deployments of a Technology Product, for example recording the number of Application components that have a Deploys To reference from a Technology Product that is supplied by a Contract. This total can be stored in a Calculated Number field on the Contract, traversing the graph to record the contract’s level of consumption.

As stated in the introduction to this article, the approach described here can complement an organization’s contract management system. Customers who wish to use the two alongside each other should consider implementing an integration that ensures that they stay synchronized.

New or updated contracts will first appear in the Contract Management System, and the Ardoq API can be used to update Ardoq with this fresh information, ensuring that both systems remain in sync. It is beyond the scope of this article to provide detailed guidance. See the Ardoq Developer Portal for more information.

We’ve shown how a contract that supports an organizational unit with people and services can be represented with a Supports reference from the Contract to the receiving Organizational Unit. If all the contractors supplied under that contract are represented as individual Person components, you could additionally link each contractor to their contract with a Supplies reference from the Contract to the individual’s Person component. In this situation, you might choose to drop the Supports reference to the receiving Organizational Unit, because the Person component can have a Belongs To and/or a Reports To reference that can be used to identify the organizational unit or units they are assigned to.

This article has described how to add different types of contract to your Ardoq metamodel, making them a part of your Enterprise Architecture knowledge graph. Once added, they can play a role in addressing key questions of real business value, such as those listed at the beginning of this article.