TM Forum Specification

Agreement Management API REST

Specification

TMF651
Release 19.0.1
November 2019

Latest Update: TM Forum Release 19.0.1 Status: TM Forum Approved

Version 4.0.1 IPR Mode: RAND

TM Forum 2019. All Rights Reserved.

Agreement Management API REST Specification

NOTICE
Copyright © TM Forum 2019. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on
or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in
whole or in part, without restriction of any kind, provided that the above copyright notice and this section are
included on all such copies and derivative works. However, this document itself may not be modified in any way,
including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of
developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the
rules applicable to copyrights, as set forth in the TM FORUM IPR Policy, must be followed) or as required to
translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or
assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS
ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that would
necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify the TM FORUM
Team Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a
manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this deliverable.

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim of
ownership of any patent claims that would necessarily be infringed by implementations of this TM FORUM
Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a
manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this TM FORUM
Standards Final Deliverable. TM FORUM may include such claims on its website but disclaims any obligation to do
so.

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights that might
be claimed to pertain to the implementation or use of the technology described in this TM FORUM Standards Final
Deliverable or the extent to which any license under such rights might or might not be available; neither does it
represent that it has made any effort to identify any such rights. Information on TM FORUM's procedures with
respect to rights in any document or deliverable produced by a TM FORUM Collaboration Project Team can be
found on the TM FORUM website. Copies of claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to obtain a general license or permission for the
use of such proprietary rights by implementers or users of this TM FORUM Standards Final Deliverable, can be
obtained from the TM FORUM Team Administrator. TM FORUM makes no representation that any information or
list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential
Claims.

© TM Forum 2019. All Rights Reserved Page 2 of 44

Agreement Management API REST Specification

Direct inquiries to the TM Forum office:

4 Century Drive, Suite 100

Parsippany, NJ 07054, USA
Tel No. +1 973 944 5100
Fax No. +1 973 998 7916
TM Forum Web Page: www.tmforum.org

© TM Forum 2019. All Rights Reserved Page 3 of 44

Agreement Management API REST Specification

TABLE OF CONTENTS
NOTICE ............................................................................................................................................................................ 2

Table of Contents............................................................................................................................................................ 4

List of Tables ................................................................................................................................................................... 6

Introduction .................................................................................................................................................................... 7

SAMPLE USE CASES ......................................................................................................................................................... 8

Support of polymorphism and extension patterns ........................................................................................................ 9

RESOURCE MODEL ........................................................................................................................................................ 10

MANAGED ENTITY AND TASK RESOURCE MODELS ................................................................................ 10

Agreement resource .............................................................................................................................................. 10

Agreement Specification resource ........................................................................................................................ 15

NOTIFICATION RESOURCE MODELS ............................................................................................................ 20

Agreement Create Event ....................................................................................................................................... 21

Agreement Attribute Value Change Event ............................................................................................................ 22

Agreement State Change Event ............................................................................................................................ 22

Agreement Delete Event ....................................................................................................................................... 22

Agreement Specification Create Event.................................................................................................................. 23

Agreement Specification Attribute Value Change Event ...................................................................................... 23

Agreement Specification State Change Event ....................................................................................................... 24

Agreement Specification Delete Event.................................................................................................................. 24

API OPERATIONS ........................................................................................................................................................... 25

Operations on Agreement ........................................................................................................................................ 26

List agreements ..................................................................................................................................................... 26

Retrieve agreement ............................................................................................................................................... 26

Create agreement.................................................................................................................................................. 28

Patch agreement ................................................................................................................................................... 31

Delete agreement.................................................................................................................................................. 33

© TM Forum 2019. All Rights Reserved Page 4 of 44

Agreement Management API REST Specification

Operations on Agreement Specification .................................................................................................................. 33

List agreement specifications ................................................................................................................................ 33

Retrieve agreement specification ......................................................................................................................... 34

Create agreement specification ............................................................................................................................ 36

Patch agreement specification .............................................................................................................................. 38

Delete agreement specification ............................................................................................................................ 39

API NOTIFICATIONS....................................................................................................................................................... 40

Register listener ........................................................................................................................................................ 40

Unregister listener .................................................................................................................................................... 41

Publish Event to listener ........................................................................................................................................... 41

Acknowledgements ...................................................................................................................................................... 43

Document History ..................................................................................................................................................... 43

Version History ...................................................................................................................................................... 43

Release History ...................................................................................................................................................... 43

Contributors to Document .................................................................................................................................... 44

© TM Forum 2019. All Rights Reserved Page 5 of 44

Agreement Management API REST Specification

LIST OF TABLES

N/A

© TM Forum 2019. All Rights Reserved Page 6 of 44

Agreement Management API REST Specification

INTRODUCTION

The Agreement API provides standardized mechanism for managing agreements, especially in the context on
partnerships between partners.

The API allows creation, update and query of agreement instances as well as creation, update and query of
agreement specifications – serving as templates for agreement instances.

The following APIs are typically used in conjunction with this API:
- Product Catalog Management API to refer to the product offerings that are linked to the agreements or
agreement specifications.
- Party Management API to refer to the engaged parties that have signed wagreements

© TM Forum 2019. All Rights Reserved Page 7 of 44

Agreement Management API REST Specification

SAMPLE USE CASES

Relevant examples of use cases for this API can be found in the Partnership Management API – Use Case section. In
the partnership AP, a Partnership Specifications typically declare Agreement Specifications, and Partnership
instances declare Party Roles instances that declare the Agreements that apply to them.

© TM Forum 2019. All Rights Reserved Page 8 of 44

Agreement Management API REST Specification

SUPPORT OF POLYMORPHISM AND EXTENSION

PATTERNS

Support of polymorphic collections and types and schema based extension is provided by means of a list of generic
meta-attributes that we describe below. Polymorphism in collections occurs when entities inherit from base
entities, for instance a BillingAccount and SettlementAccount inheriting properties from the abstract Account
entity.

Generic support of polymorphism and pattern extensions is described in the TMF API Guidelines v3.0 Part 2
document.

The @type attribute provides a way to represent the actual class type of an entity. For example, within a list of
Account instances some may be instances of BillingAccount where other could be instances of SettlementAccount.
The @type gives this information. All resources and sub-resources of this API have a @type attributes that can be
provided when this is useful.

The @referredType can be used within reference entities (like for instance an AccountRef object) to explicitly
denote the actual entity type of the referred class. Notice that in reference entities the @type, when used, denotes
the class type of the reference itself, such as BillingAccountRef or SettlementAccountRef, and not the class type of
the referred object. However since reference classes are rarely sub-classed, @type is generally not useful in
reference objects.

The @schemaLocation property can be used in resources to allow specifying user-defined properties of an Entity or
to specify the expected characteristics of an entity.

The @baseType attribute gives a way to provide explicitly the base of class of a given resource that has been
extended.

© TM Forum 2019. All Rights Reserved Page 9 of 44

Agreement Management API REST Specification

RESOURCE MODEL
MANAGED ENTITY AND TASK RESOURCE MODELS

Agreement resource
An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law,
such as a service level agreement or a customer price agreement. An agreement involves a number of other
business entities, such as products, services, and resources and/or their specifications.

Resource model

Field descriptions

Agreement fields

agreementAuthorization A list of agreement authorizations (AgreementAuthorization [*]). A business

participant that is responsible for approving the agreement.

© TM Forum 2019. All Rights Reserved Page 10 of 44

Agreement Management API REST Specification

agreementItem A list of agreement items (AgreementItem [1..*]). A part of the agreement expressed
in terms of a product offering and possibly including specific terms and conditions.

agreementPeriod A time period. The time period during which the Agreement is in effect.

agreementSpecification An agreement specification reference (AgreementSpecificationRef). An

AgreementSpecification represents a template of an agreement that can be used
when establishing partnerships.

agreementType A string. The type of the agreement. For example commercial.

associatedAgreement A list of agreement references (AgreementRef [*]). An agreement represents a

contract or arrangement, either written or verbal and sometimes enforceable by law,
such as a service level agreement or a customer price agreement. An agreement
involves a number of other business entities, such as products, services, and
resources and/or their specifications.

characteristic A list of characteristics (Characteristic [*]). Describes a given characteristic of an

object or entity through a name/value pair.

completionDate A time period. Date at which the agreement is completed.

description A string. Narrative that explains the agreement and details about the it , such as why
the agreement is taking place.

documentNumber An integer. A reference number assigned to an Agreement that follows a prescribed

numbering system.

engagedParty A list of related parties (RelatedParty [1..*]). Related Entity reference. A related party
defines party or party role linked to a specific entity.

href A string. Unique url identifying the agreement as a resource.

id A string. Unique identifier for the agreement.

initialDate A date time (DateTime). Date at which the agreement was initialized.

name A string. A human-readable name for the agreement.

statementOfIntent A string. An overview and goals of the Agreement.

status A string. The current status of the agreement. Typical values are: in process, approved
and rejected.

version A string. A string identifying the version of the agreement.

AgreementAuthorization sub-resource

A business participant that is responsible for approving the agreement.

© TM Forum 2019. All Rights Reserved Page 11 of 44

Agreement Management API REST Specification

date A date time (DateTime). The date associated with the authorization state.

signatureRepresentation A string. Indication that represents whether the signature is a physical paper
signature or a digital signature.

state A string. Current status of the authorization, for example in process, approved,
rejected.

AgreementItem sub-resource

A part of the agreement expressed in terms of a product offering and possibly including specific terms and
conditions.

product A list of product references (ProductRef [*]). The list of products indirectly referred by
this agreement item (since an agreement item refers primarily to product offerings).

productOffering A list of product offering references (ProductOfferingRef [*]). The list of product
offerings referred by this agreement item.

termOrCondition A list of agreement term or conditions (AgreementTermOrCondition [*]). Aspects of

the agreement not formally specified elsewhere in the agreement and that cannot be
captured elsewhere in a formal notation, or automatically monitored and require a
more human level of management.

AgreementTermOrCondition sub-resource

Aspects of the agreement not formally specified elsewhere in the agreement and that cannot be captured
elsewhere in a formal notation, or automatically monitored and require a more human level of management.

description A string. Text that explains the term or condition of the agreement.

id A string. Unique number assigned for reference.

validFor A time period. The period of time during which the term or condition of the
agreement applies.

Characteristic sub-resource

Describes a given characteristic of an object or entity through a name/value pair.

name A string. Name of the characteristic.

value An any (Any). The value of the characteristic.

valueType A string. Data type of the value of the characteristic.

RelatedParty sub-resource

Related Entity reference. A related party defines party or party role linked to a specific entity.

© TM Forum 2019. All Rights Reserved Page 12 of 44

Agreement Management API REST Specification

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

role A string. Role played by the related party.

AgreementRef relationship

Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes
enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a
number of other business entities, such as products, services, and resources and/or their specifications.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the agreement.

AgreementSpecificationRef relationship

AgreementSpecification reference. An AgreementSpecification represents a template of an agreement that can be

used when establishing partnerships.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the agreement specification.

description A string. A narrative that explains in detail what the agreement specification is about.

ProductOfferingRef relationship

ProductOffering reference. A product offering represents entities that are orderable from the provider of the
catalog, this resource includes pricing information.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

© TM Forum 2019. All Rights Reserved Page 13 of 44

Agreement Management API REST Specification

ProductRef relationship

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

Json representation sample

We provide below the json representation of an example of a 'Agreement' resource object

{
"@type": "Agreement",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreement/40",
"id": "40",
"name": "Moon",
"status": "Pending",
"documentNumber": "97867",
"version": "1.0",
"agreementSpecification": {
"href": "https://host:port/tmf-api/agreementManagement/v4/agreementSpecification/1140",
"id": "1140",
"name": "Moon Agreement Template"
},
"validFor": {
"startDateTime": "2018-06-12T00:00Z",
"endDateTime": "2019-01-11T00:00Z"
},
"engagedParty": [
{
"@type": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v4/organization/500",
"id": "500",
"name": "Happy Travellers"
}
],
"characteristic": [
{
"name": "fidelityProgram",
"value": "premium",
"valueType": "string"
}
],
"relatedParty": [
{
"href": "https://host:port/tmf-api/partyManagement/v4/organization/2777",
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}

© TM Forum 2019. All Rights Reserved Page 14 of 44

Agreement Management API REST Specification

],
"agreementItem": [
{
"productOffering": {
"href": "https://host:port/tmf-api/productCatalogManagement/v4/productOffering/61",
"name": "ChristmasToy"
},
"termOrCondition": {
"id": "1",
"description": "delivery should be done in France"
}
}
]
}

Agreement Specification resource

A template of an agreement that can be used when establishing partnerships.

Resource model

© TM Forum 2019. All Rights Reserved Page 15 of 44

Agreement Management API REST Specification

Field descriptions

AgreementSpecification fields

attachment A list of attachment ref or values (AttachmentRefOrValue [1..*]). An attachment by

value or by reference. An attachment complements the description of an element,
for example through a document, a video, a picture.

description A string. A narrative that explains in detail what the agreement specification is
about.

href A string. Reference of the agreement specification.

id A string. Unique identifier of the agreement specification.

© TM Forum 2019. All Rights Reserved Page 16 of 44

Agreement Management API REST Specification

isBundle A boolean. If true, this agreement specification is a grouping of other agreement

specifications. The list of bundled agreement specifications is provided by the
specificationRelationship property.

lastUpdate A date time (DateTime). Date and time of the last update.

lifecycleStatus A string. Indicates the current lifecycle status.

name A string. Name of the agreement specification.

relatedParty A list of related parties (RelatedParty [*]). Related Entity reference. A related party
defines party or party role linked to a specific entity.

serviceCategory A category reference (CategoryRef). The category for grouping recommendations.

specificationCharacteristic A list of agreement spec characteristics (AgreementSpecCharacteristic [*]). A

characteristic quality or distinctive feature of an agreement.

specificationRelationship A list of agreement specification relationships (AgreementSpecificationRelationship

[*]). A relationship between agreement specifications. Typical relationships are
substitution and dependency.

validFor A time period. The period for which the agreement specification is valid.

version A string. Agreement specification version.

AgreementSpecCharacteristic sub-resource

A characteristic quality or distinctive feature of an agreement.

configurable A boolean. If true, the Boolean indicates that the characteristic is configurable.

description A string. A narrative that explains in detail what the characteristic is.

name A string. Name of the characteristic being specified.

specCharacteristicValue A list of agreement spec characteristic values (AgreementSpecCharacteristicValue [*]).

A number or text that can be assigned to an agreement specification characteristic.

validFor A time period. The period for which the specification characteristic is valid.

valueType A string. A kind of value that the characteristic can take on, such as numeric, text and
so forth.

AgreementSpecCharacteristicValue sub-resource

A number or text that can be assigned to an agreement specification characteristic.

default A boolean. Indicates if the value is the default value for a characteristic.

© TM Forum 2019. All Rights Reserved Page 17 of 44

Agreement Management API REST Specification

unitOfMeasure A string. Unit of measure for the characteristic, such as minutes, gigabytes (GB) and so
on.

validFor A time period. The period of time for which a value is applicable.

value An any (Any). A discrete value that the characteristic can take on.

valueFrom A string. The low range value that a characteristic can take on.

valueTo A string. The upper range value that a characteristic can take on.

valueType A string. A kind of value that the characteristic can take on, such as numeric, text, and
so forth.

AgreementSpecificationRelationship sub-resource

A relationship between agreement specifications. Typical relationships are substitution and dependency.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

relationshipType A string. Type of relationship such as, substitution or dependency.

validFor A time period. The period for which the relationship is valid.

AttachmentRefOrValue sub-resource

An attachment by value or by reference. An attachment complements the description of an element, for example
through a document, a video, a picture.

@referredType A string. The actual type of the target instance when needed for disambiguation.

description A string. A narrative text describing the content of the attachment.

href A string. URI for this Attachment.

id A string. Unique identifier for this particular attachment.

url A string. Uniform Resource Locator, is a web page address (a subset of URI).

name A string. The name of the attachment.

attachmentType A string. Attachment type such as video, picture.

content A string. The actual contents of the attachment object, if embedded, encoded as
base64.

© TM Forum 2019. All Rights Reserved Page 18 of 44

Agreement Management API REST Specification

mimeType A string. Attachment mime type such as extension file for video, picture and
document.

size A quantity (Quantity). The size of the attachment.

validFor A time period. The period of time for which the attachment is valid.

Quantity sub-resource

An amount in a given unit.

amount A float. Numeric value in a given unit.

units A string. Unit.

RelatedParty sub-resource

Related Entity reference. A related party defines party or party role linked to a specific entity.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

role A string. Role played by the related party.

CategoryRef relationship

The category for grouping recommendations.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the related entity.

id A string. Unique identifier of a related entity.

name A string. Name of the related entity.

version A string. Category version.

Json representation sample

We provide below the json representation of an example of a 'AgreementSpecification' resource object

{
"@type": "AgreementSpecification",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreementSpecification/1140",
"id": "1140",
"name": "Moon Agreement Template",
"lifecycleStatus": "Approved",

© TM Forum 2019. All Rights Reserved Page 19 of 44

Agreement Management API REST Specification

"version": "2.0",
"validFor": {
"startDateTime": "2018-06-12T00:00Z",
"endDateTime": "2019-01-11T00:00Z"
},
"specificationCharacteristic": [
{
"name": "fidelityProgram",
"configurable": true,
"valueType": "string"
}
],
"relatedParty": [
{
"@referredType": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v4/organization/2777",
"id": "2777",
"name": "John Doe",
"role": "bill receiver"
}
]
}

NOTIFICATION RESOURCE MODELS

8 notifications are defined for this API

Notifications related to Agreement:

- AgreementCreateEvent
- AgreementAttributeValueChangeEvent
- AgreementStateChangeEvent
- AgreementDeleteEvent

Notifications related to AgreementSpecification:

- AgreementSpecificationCreateEvent
- AgreementSpecificationAttributeValueChangeEvent
- AgreementSpecificationStateChangeEvent
- AgreementSpecificationDeleteEvent

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification event resource (depicted by "SpecificEvent" placeholder) is a sub class of a generic Event structure
containing at least an id of the event occurrence (eventId), an event timestamp (eventTime), and the name of the
resource (eventType).

This notification structure owns an event payload structure ("SpecificEventPayload" placeholder) linked to the
resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

© TM Forum 2019. All Rights Reserved Page 20 of 44

Agreement Management API REST Specification

Agreement Create Event

Notification AgreementCreateEvent case for resource Agreement

Json representation sample

We provide below the json representation of an example of a 'AgreementCreateEvent' notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementCreateEvent",
"event": {
"agreement" :

© TM Forum 2019. All Rights Reserved Page 21 of 44

Agreement Management API REST Specification

{-- SEE Agreement RESOURCE SAMPLE --}

}
}

Agreement Attribute Value Change Event

Notification AgreementAttributeValueChangeEvent case for resource Agreement

Json representation sample

We provide below the json representation of an example of a 'AgreementAttributeValueChangeEvent' notification

event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementAttributeValueChangeEvent",
"event": {
"agreement" :
{-- SEE Agreement RESOURCE SAMPLE --}
}
}

Agreement State Change Event

Notification AgreementStateChangeEvent case for resource Agreement

Json representation sample

We provide below the json representation of an example of a 'AgreementStateChangeEvent' notification event

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementStateChangeEvent",
"event": {
"agreement" :
{-- SEE Agreement RESOURCE SAMPLE --}
}
}

Agreement Delete Event

Notification AgreementDeleteEvent case for resource Agreement

Json representation sample

We provide below the json representation of an example of a 'AgreementDeleteEvent' notification event object

© TM Forum 2019. All Rights Reserved Page 22 of 44

Agreement Management API REST Specification

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementDeleteEvent",
"event": {
"agreement" :
{-- SEE Agreement RESOURCE SAMPLE --}
}
}

Agreement Specification Create Event

Notification AgreementSpecificationCreateEvent case for resource AgreementSpecification

Json representation sample

We provide below the json representation of an example of a 'AgreementSpecificationCreateEvent' notification

event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementSpecificationCreateEvent",
"event": {
"agreementSpecification" :
{-- SEE AgreementSpecification RESOURCE SAMPLE --}
}
}

Agreement Specification Attribute Value Change Event

Notification AgreementSpecificationAttributeValueChangeEvent case for resource AgreementSpecification

Json representation sample

We provide below the json representation of an example of a 'AgreementSpecificationAttributeValueChangeEvent'

notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementSpecificationAttributeValueChangeEvent",
"event": {
"agreementSpecification" :
{-- SEE AgreementSpecification RESOURCE SAMPLE --}
}
}

© TM Forum 2019. All Rights Reserved Page 23 of 44

Agreement Management API REST Specification

Agreement Specification State Change Event

Notification AgreementSpecificationStateChangeEvent case for resource AgreementSpecification

Json representation sample

We provide below the json representation of an example of a 'AgreementSpecificationStateChangeEvent'

notification event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementSpecificationStateChangeEvent",
"event": {
"agreementSpecification" :
{-- SEE AgreementSpecification RESOURCE SAMPLE --}
}
}

Agreement Specification Delete Event

Notification AgreementSpecificationDeleteEvent case for resource AgreementSpecification

Json representation sample

We provide below the json representation of an example of a 'AgreementSpecificationDeleteEvent' notification

event object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"AgreementSpecificationDeleteEvent",
"event": {
"agreementSpecification" :
{-- SEE AgreementSpecification RESOURCE SAMPLE --}
}
}

© TM Forum 2019. All Rights Reserved Page 24 of 44

Agreement Management API REST Specification

API OPERATIONS
Remember the following Uniform Contract:

Operation on Entities Uniform API Operation Description

Query Entities GET Resource GET must be used to retrieve

a representation of a
resource.

Create Entity POST Resource POST must be used to create

a new resource

Partial Update of an Entity PATCH Resource PATCH must be used to

partially update a resource

Complete Update of an PUT Resource PUT must be used to

Entity completely update a
resource identified by its
resource URI

Remove an Entity DELETE Resource DELETE must be used to

remove a resource

Execute an Action on an POST on TASK Resource POST must be used to

Entity execute Task Resources

Other Request Methods POST on TASK Resource GET and POST must not be
used to tunnel other request
methods.

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

© TM Forum 2019. All Rights Reserved Page 25 of 44

Agreement Management API REST Specification

Operations on Agreement

List agreements

GET /agreement?fields=...&{filtering}
Description

This operation list agreement entities.

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Retrieving all approved agreements of engaged party 'So Magic Ltd'. The result items are shrinked to show only the
id and name(fields=id,name)

Request

GET /tmf-api/agreementManagement/v4/agreement?fields=id,name&status=approved&engagedParty.name="So Magic

Ltd"
Accept: application/json

Response

200

[
{
"id": "8756",
"name": "Employment Quota"
},
{
"id": "9435",
"name": "Zero Bug"
}
]

Retrieve agreement

GET /agreement/{id}?fields=...&{filtering}
Description

This operation retrieves an agreement entity.

Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

© TM Forum 2019. All Rights Reserved Page 26 of 44

Agreement Management API REST Specification

Usage Samples

Here's an example of a request for retrieving an Agreement resource

Request

GET /tmf-api/agreementManagement/v4/agreement/4989
Accept: application/json

Response

200

{
"@type": "Agreement",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreement/4989",
"id": "4989",
"description": "This agreement ...",
"name": "Summer Contract Agreement",
"initialDate": "2015-10-16T00:00Z",
"completionDate": "2018-11-25T00:00Z",
"agreementPeriod": {
"startDateTime": "2018-04-20T00:00",
"endDateTime": "2018-11-20T00:00"
},
"documentNumber": 11,
"statementOfIntent": "Agreement on minimum prices",
"status": "process",
"agreementType": "commercial",
"version": "1.5",
"agreementSpecification": {
"@referredType": "AgreementSpecification",
"description": "This agreement specification defines the environment protection rules to be followed by each
party.",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreementSpecification/2633",
"id": "2633",
"name": "General Agreement Specification"
},
"agreementItem": [
{
"productOffering": [
{
"@typr": "ProductOffering",
"href": "https://host:port/tmf-api/productCatalogManagement/v4/productOffering/9085",
"id": "9085",
"name": "My Quick BB Offer"
}
],
"termOrCondition": [
{
"description": "This agreement term or condition ...",

© TM Forum 2019. All Rights Reserved Page 27 of 44

Agreement Management API REST Specification

"id": "5890",
"validFor": {
"startDateTime": "2018-04-25T00:00",
"endDateTime": "2018-11-20T00:00"
}
}
]
}
],
"engagedParty": [
{
"@referredType": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v4/organization/330",
"id": "330",
"role": "Supplier",
"name": "Magic Tools Company"
}
],
"agreementAuthorization": [
{
"date": "2018-04-24T00:00Z",
"signatureRepresentation": "Dr Mabuse",
"state": "approved"
}
],
"characteristic": [
[
{
"name": "country",
"value": "Spain"
},
{
"name": "confidentialLevel",
"value": "high"
}
]
],
"associatedAgreement": [
[
{
"@referredType": "Agreement",
"name": "General Partnership Agreement",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreement/5453"
}
]
]
}

Create agreement

POST /agreement

© TM Forum 2019. All Rights Reserved Page 28 of 44

Agreement Management API REST Specification

Description

This operation creates an agreement entity.

Mandatory and Non Mandatory Attributes

The following tables provide the list of mandatory and non mandatory attributes when creating a Agreement,
including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add
additional mandatory attributes.

Mandatory Attributes Rule

agreementItem
engagedParty
name
agreementType

Non Mandatory Attributes Rule

agreementAuthorization
agreementPeriod
agreementSpecification
associatedAgreement
characteristic
completionDate
description
documentNumber
initialDate
statementOfIntent
status
version

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships when
creating a Agreement resource.

Context Mandatory Sub-Attributes

engagedParty name

Default Values

When creating the resource, the following table provides the default values applicable to optional attributes of the
resource (or sub-resources).

Attributes Default Value

completionDate Current date
version 0

© TM Forum 2019. All Rights Reserved Page 29 of 44

Agreement Management API REST Specification

Usage Samples

Here's an example of a request for creating an Agreement resource.

Request

POST /tmf-api/agreementManagement/v4/agreement
Content-Type: application/json

{
"name": "Summer Contract Agreement",
"agreementType": "commercial",
"agreementItem": [
{
"productOffering": [
{
"@referredType": "ProductOffering",
"href": "https://host:port/tmf-api/productCatalogManagement/v4/productOffering/9085",
"id": "9085",
"name": "My Quick BB Offer"
}
],
"termOrCondition": [
{
"description": "This agreement term or condition ...",
"id": "5890",
"validFor": {
"startDateTime": "2018-04-25T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
}
}
]
}
],
"engagedParty": [
{
"@referredType": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v4/organization/330",
"id": "330",
"role": "Supplier",
"name": "Magic Tools Company"
}
]
}

Response

201

{
"@type": "Agreement",

© TM Forum 2019. All Rights Reserved Page 30 of 44

Agreement Management API REST Specification

"href": "https://host:port/tmf-api/agreementManagement/v4/agreement/28",
"id": "28",
"name": "Summer Contract Agreement",
"agreementType": "commercial",
"agreementItem": [
{
"productOffering": [
{
"@referredType": "ProductOffering",
"href": "https://host:port/tmf-api/productCatalogManagement/v4/productOffering/9085",
"id": "9085",
"name": "My Quick BB Offer"
}
],
"termOrCondition": [
{
"description": "This agreement term or condition ...",
"id": "5890",
"validFor": {
"startDateTime": "2018-04-25T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
}
}
]
}
],
"engagedParty": [
{
"@referredType": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v4/organization/330",
"id": "330",
"role": "Supplier",
"name": "Magic Tools Company"
}
]
}

Patch agreement

PATCH /agreement/{id}
Description

This operation allows partial updates of an agreement entity. Support of json/merge

(https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is
optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning
mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH
operation. Hence these tables are not repeated here.

© TM Forum 2019. All Rights Reserved Page 31 of 44

Agreement Management API REST Specification

Patchable and Non-Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their
usage.

Patchable Attributes Rule

agreementAuthorization
agreementItem
agreementPeriod
agreementSpecification
agreementType
associatedAgreement
characteristic
description
documentNumber
engagedParty
initialDate
name
statementOfIntent
status
version

Non Patchable Attributes Rule

completionDate
href
id

Usage Samples

Here's an example of a request for patching a Agreement resource.

Changing the status of the agreement as rejected (using JSON merge-patch).

Request

PATCH /tmf-api/agreementManagement/v4/agreement/42
Content-Type: application/merge-patch+json

{
"status": "rejected"
}

Response

200

© TM Forum 2019. All Rights Reserved Page 32 of 44

Agreement Management API REST Specification

{ Similar JSON as in GET response with status changed }

Delete agreement

DELETE /agreement/{id}
Description

This operation deletes an agreement entity.

Usage Samples

This operation deletes a Agreement resource.

Request

DELETE /tmf-api/agreementManagement/v4/agreement/42

Response

204

Operations on Agreement Specification

List agreement specifications

GET /agreementSpecification?fields=...&{filtering}
Description

This operation list agreement specification entities.

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Retrieving all agreement specifications with the government army. The result items are shrinked to show only the
id and name (fields=id,name).

© TM Forum 2019. All Rights Reserved Page 33 of 44

Agreement Management API REST Specification

Request

GET /tmf-api/agreementManagement/v4/agreementSpecification?fields=id,name&relatedParty.name="Army"
Accept: application/json

Response

200

[
{
"id": "5434",
"name": "General Maintenance"
},
{
"id": "9080",
"name": "Secret"
}
]

Retrieve agreement specification

GET /agreementSpecification/{id}?fields=...&{filtering}
Description

This operation retrieves an agreement specification entity.

Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving an AgreementSpecification resource

Request

GET /tmf-api/agreementManagement/v4/agreementSpecification/9320
Accept: application/json

Response

200

© TM Forum 2019. All Rights Reserved Page 34 of 44

Agreement Management API REST Specification

{
"@type": "AgreementSpecification",
"description": "This agreement specification defines the environment protection rules to be followed by each party.",
"href": "https://host:port/tmf-api/agreementManagement/v2/agreementSpecification/9320",
"id": "9320",
"isBundle": false,
"lastUpdate": "2018-04-24T00:00Z",
"lifecycleStatus": "initialized",
"name": "General Agreement Specification",
"validFor": {
"startDateTime": "2018-04-23T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
},
"version": "3.0",
"serviceCategory": {
"href": "https://host:port/tmf-api/productCatalogManagement/v2/category/1545",
"id": "1545",
"name": "Secure Home"
},
"specCharacteristic": [
{
"configurable": true,
"description": "This agreement spec characteristic ...",
"name": "Phone color",
"validFor": {
"startDateTime": "2018-04-27T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
},
"valueType": "string",
"specCharacteristicValue": [
{
"default": false,
"unitOfMeasure": "Hz",
"validFor": {
"startDateTime": "2018-04-27T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
},
"value": "yellow",
"valueType": "string"
}
]
}
],
"relatedParty": [
{
"@referredParty": "Organization",
"href": "https://host:port/tmf-api/partyManagement/v2/organization/7401",
"id": "7401",
"name": "Jimmy Doe",
"role": "bill responsible"
}
],
"attachment": [
{
"@referredParty": "Attachment",

© TM Forum 2019. All Rights Reserved Page 35 of 44

Agreement Management API REST Specification

"href": "http://hostname:port/tmf-api/documentManagement/v1/attachment/44",
"id": "44",
"attachmentType": "Video",
"url": "http://xxxxx"
}
],
"specificationRelationship": [
{
"@type": "AgreementSpecification",
"href": "https://host:port/tmf-api/agreementManagement/v2/agreementSpecification/2481",
"id": "2481",
"relationshipType": "dependency",
"validFor": {
"startDateTime": "2018-04-23T00:00Z",
"endDateTime": "2018-11-20T00:00Z"
}
}
]
}

Create agreement specification

POST /agreementSpecification
Description

This operation creates an agreement specification entity.

Mandatory and Non Mandatory Attributes

The following tables provide the list of mandatory and non mandatory attributes when creating a
AgreementSpecification, including any possible rule conditions and applicable default values. Notice that it is up to
an implementer to add additional mandatory attributes.

Mandatory Attributes Rule

attachment
name

Non Mandatory Attributes Rule

description
isBundle
lastUpdate
lifecycleStatus
relatedParty
serviceCategory
specificationCharacteristic
specificationRelationship
validFor
version

© TM Forum 2019. All Rights Reserved Page 36 of 44

Agreement Management API REST Specification

Default Values

When creating the resource, the following table provides the default values applicable to optional attributes of the
resource (or sub-resources).

Attributes Default Value

isBundle False

Usage Samples

Here's an example of a request for creating an AgreementSpecification resource.

Request

POST /tmf-api/agreementManagement/v4/agreementSpecification
Content-Type: application/json

{
"name": "General Agreement Specification",
"attachment": [
{
"href": "http://tmf-api/name:port/tmf-api/documentManagement/v1/attachment/44",
"id": "44",
"attachmentType": "Video",
"url": "http://xxxxx"
}
]
}

Response

201

{
"@type": "AgreementSpecification",
"href": "https://host:port/tmf-api/agreementManagement/v4/agreementSpecification/9320",
"id": "9320",
"isBundle": false,
"name": "General Agreement Specification",
"attachment": [
{
"@referredType": "Attachment",
"href": "http://hostname:port/tmf-api/documentManagement/v4/attachment/44",
"id": "44",
"attachmnentType": "Video",
"url": "http://xxxxx"
}
]
}

© TM Forum 2019. All Rights Reserved Page 37 of 44

Agreement Management API REST Specification

Patch agreement specification

PATCH /agreementSpecification/{id}
Description

This operation allows partial updates of an agreement specification entity. Support of json/merge
(https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is
optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning
mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH
operation. Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their
usage.

Patchable Attributes Rule

attachment
description
isBundle
lastUpdate
lifecycleStatus
name
relatedParty
serviceCategory
specificationCharacteristic
specificationRelationship
validFor
version

Non Patchable Attributes Rule

href
id

Usage Samples

Here's an example of a request for patching an AgreementSpecification resource.

Adding an attachment document to the the agreement specification (using JSON merge-patch).

Request

PATCH /tmf-api/agreementManagement/v4/agreementSpecification/42
Content-Type: application/merge-patch+json

© TM Forum 2019. All Rights Reserved Page 38 of 44

Agreement Management API REST Specification

{
"attachment": [
{
"url": "http://www.allmydocs.fr/agreement_standard.pdf",
"agreementType": "Document"
}
]
}

Response

200

{ Similar JSON as in GET response with attachment changed }

Delete agreement specification

DELETE /agreementSpecification/{id}
Description

This operation deletes an agreement specification entity.

Usage Samples

This operation deletes a AgreementSpecification resource.

Request

DELETE /tmf-api/agreementManagement/v4/agreementSpecification/42

Response

204

© TM Forum 2019. All Rights Reserved Page 39 of 44

Agreement Management API REST Specification

API NOTIFICATIONS
For every single of operation on the entities use the following templates and provide sample REST
notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST
Guidelines reproduced below.

Register listener
POST /hub
Description

Sets the communication endpoint address the service instance must use to deliver information about its health
state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not
support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created
again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.

Request

POST /api/hub
Accept: application/json

{"callback": "http://in.listener.com"}

Response

201
Content-Type: application/json
Location: /api/hub/42

{"id":"42","callback":"http://in.listener.com","query":null}

© TM Forum 2019. All Rights Reserved Page 40 of 44

Agreement Management API REST Specification

Unregister listener
DELETE /hub/{id}
Description

Clears the communication endpoint address that was set by creating the Hub.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.

Request

DELETE /api/hub/42
Accept: application/json

Response

204

Publish Event to listener

POST /client/listener
Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the
callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

© TM Forum 2019. All Rights Reserved Page 41 of 44

Agreement Management API REST Specification

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by
one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY
refers to the data structure of the given notification type.

Request

POST /client/listener
Accept: application/json

{
"event": {
EVENT BODY
},
"eventType": "EVENT_TYPE"
}

Response

201

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design
Guidelines.

© TM Forum 2019. All Rights Reserved Page 42 of 44

Any Management API REST Specification

ACKNOWLEDGEMENTS
Document History

Version History

Version Date Release led by: Description

Number

1.0 15-Apr-2016 Pierre Gauthier First Release of the Document.

TM Forum Generated from the API Data Model.
[email protected]

Mariano Belaunde
Orange
[email protected]

2.0 24-Apr-2018 Mariano Belaunde Update with minor changes to

comply with Guidelines V3.0

Release 2.0.1 27-Jun-2018 Adrienne Walcott Formatting/style edits prior to R18

publishing

Release 2.0.2 10-Sep-2018 Adrienne Walcott Updated to reflect TM Forum

Approved Status

4.0 11-Aug-2019 Mariano Belaunde Regeneration after schematization

Orange Labs

4.0.1 29-Nov-2019 Adrienne Walcott Updated to reflect TM Forum

Approved Status

Release History

Release Date Release led by: Description

Number

Release 18.0.0 25-Jun-2018 Pierre Gauthier Initial Release

Mariano Belaunde

Release 18.0.1 10-Sep-2018 Adrienne Walcott Updated to reflect TM Forum

Approved Status

Release 19.0.0 11-Aug-2019 Mariano Belaunde Regeneration after schematization

Orange Labs

© TM Forum 2019. All Rights Reserved Page 43 of 44

Any Management API REST Specification

Release Date Release led by: Description

Number

19.0.1 29-Nov-2019 Adrienne Walcott Updated to reflect TM Forum

Approved Status

Contributors to Document

Veronique Mauneau Orange

Jean-Luc Tymen Orange

Mariano Belaunde Orange

Elaine Haher Ericsson

August-Wilhelm Jagau Ericsson

Liuyiling (Sammy) Huawei

Sunruinan Huawei

Jiang Yisong Huawei

George Glass BT

Pierre Gauthier TM Forum

© TM Forum 2019. All Rights Reserved Page 44 of 44