Page tree

 

Frameworx Specification

 

Privacy Management API REST Specification

 

 

 

 

 

 

      TMF644

      Release 16.0.1

      October 2016

 

 

 

Latest Update: Frameworx Release 16

TM Forum Approved

Version 1.0.2

IPR Mode: RAND

NOTICE

 

Copyright © TM Forum 2016. 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.

 

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

RESOURCE MODEL

Managed Entity and Task Resource Models

PARTY PRIVACY PROFILE TYPE Resource

PARTY PRIVACY PROFILE Resource

PARTY PRIVACY Agreement Resource

Export Job Resource

Import Job Resource

Notification Resource Models

API OPERATION TEMPLATES

GET /privacyManagement/partyPrivacyProfileType/{ID}

GET /privacyManagement/partyPrivacyProfile/{ID}

GET /privacyManagement/partyPrivacyAgreement/{ID}

PATCH /privacyManagement/partyPrivacyProfileType/{ID}

PATCH /privacyManagement/partyPrivacyProfile/{ID}

PATCH /privacyManagement/partyPrivacyAgreement/{ID}

POST /privacyManagement/partyPrivacyProfileType

POST /privacyManagement/partyPrivacyProfile

POST /privacyManagement/partyPrivacyAgreement

DELETE /privacyManagement/partyPrivacyProfileType/{ID} or /partyPrivacyProfile/{ID} or /partyPrivacyAgreement/{ID}

POST /privacyManagement/importJob

POST /privacyManagement/exportJob

GET privacyManagement/exportJob

GET privacyManagement/importJob

API NOTIFICATION TEMPLATES

REGISTER LISTENER POST /hub

UNREGISTER LISTENER DELETE hub/{id}

publish {EventTYPE} POST /listener

ACKNOWLEDGMENTS

VERSION HISTORY

RELEASE HISTORY

Contributors to Document

 

List of Tables

 

N/A

 

Introduction

The following document is the specification of the REST API Privacy Management.

The Privacy management API provides standardized mechanism for privacy profile types, privacy profiles and privacy agreements such as creation, update, retrieval, deletion and notification of events.

Privacy management API manages the following data resources:

-           Privacy Profile Type

  • Privacy profile type represents a description for privacy profiles.
  • Main privacy profile type attributes are its identifier, name, description, version, last update, lifecycle status, validity period, characteristics and their values, related parties, applicable roles.

-           Privacy Profile

  • Privacy profile represents the set of Privacy settings defined for a Party
  • Main privacy profile attributes are its identifier, name, description, date of creation, status, validity period, privacy profile type, characteristics values, agreement, the party who has agreed.

-           Privacy Agreement

  • Privacy agreement represents the approval made by the Party about a Party Privacy Profile
  • Main privacy agreement attributes are its identifier, name, description, agreement period, initial date, completion date, document number, statement of intent, status, type, version, agreement specification, agreement items, engaged party, agreement authorization, characteristics, associated agreements, privacy profile and privacy profile characteristic values.

Privacy management API performs the following operations on privacy profile types, privacy profiles and privacy agreements:

-           Retrieval of a privacy profile type, a privacy profile or a privacy agreement, or of a collection of them depending on filter criteria

-           Partial update of a privacy profile type, a privacy profile or a privacy agreement

-           Creation of a privacy profile type, a privacy profile or a privacy agreement

-           Deletion of a privacy profile type, a privacy profile or a privacy agreement (for administration purposes)

-           Notification of events:

  • privacy profile type create
  • privacy profile type update
  • privacy profile type delete
  • privacy profile create
  • privacy profile update
  • privacy profile delete
  • privacy agreement create
  • privacy agreement update
  • privacy agreement delete

SAMPLE USE CASES

Reader will find example of use cases using Privacy management API in “Open Digital Business Scenarios and Use Cases” document.


RESOURCE MODEL

Managed Entity and Task Resource Models

For every single resource managed by the API provide a JSON based representation of the managed entities and tasks.

 

PARTY PRIVACY PROFILE TYPE Resource

A Party Privacy Profile Type represents a description for Party Privacy Profiles.

JSON representation of a Party Privacy Profile Type:

{

  "href": "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103",

  "id": "103",

  "version": "1.0",

  "lastUpdate": "2013-04-19T16:42:23-04:00",

  "name": "Customer Mass Market Privacy",

  "description": "This is the customer mass market privacy",

  "lifecycleStatus": "active",

  "validFor": {

    "startDateTime": "2013-04-19T16:42:23-04:00",

    "endDateTime": "2013-06-19T00:00:00-04:00"

  },

  "relatedParty": [

    {

      "id": "1066",

      "href": "http://serverlocation:port/partyManagement/individual/1066",

      "role": "Profile Type Admin",

      "name": "James Smith"

    }

  ],

  "applicableRole": [

    {

      "role": "Customer"

    }

  ],

  "partyPrivacyProfileTypeCharacteristic": [

    { // ALWAYS example

      "id": "42",

      "name": "eMailAddress",

      "privacyUsagePurpose": "ADMIN",

      "description": "this is the email address privacy for internal ADMIN purpose",

      "privacyType": "Internal Purpose",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "Authorized",

          "validityDuration": "Always"

        }

      ],

      "relatedRole": [

        {

          "role": "Administrator"

        }

      ]     

    },

    { // OPT-OUT example

      "id": "43",

      "name": "eMailAddress",

      "privacyUsagePurpose": "INFORMATION",

      "description": "this is the email address privacy attributes for internal INFORMATION purpose",

      "privacyType": "Internal Purpose",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "Authorized",

          "validityDuration": "Always"

        },

        {

          "valueType": "string",

          "default": false,

          "value": "Unauthorized",

          "validityDuration": "Always"

        }

      ],

      "relatedRole": [

        {

          "role": "Vendor"

        },

        {

          "role": "Employee"

        }

      ]

    },

    { // OPT-IN example

      "id": "44",

      "name": "eMailAddress",

      "privacyUsagePurpose": "MARKETING",

      "description": "this is the email address privacy attributes for internal MARKETING purpose",

      "privacyType": "Internal Purpose",

      "criticalityLevel": "high",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "Unauthorized",

          "validityDuration": "Always"

        },

        {

          "valueType": "string",

          "default": false,

          "value": "Authorized",

          "validityDuration": "3 months"

        }

      ],

      "relatedRole": [

        {

          "role": "Vendor"

        }

      ]

    },

    { // NEVER example

      "id": "45",

      "name": "eMailAddress",

      "privacyUsagePurpose": "RESEARCH",

      "description": "this is the email address privacy attributes for internal RESEARCH purpose",

      "privacyType": "Internal Purpose",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "Unauthorized",

          "validityDuration": "Always"

        }

      ],

      "relatedRole": [

        {

          "role": "Employee"

        }

      ]

    },

    { // External purpose example

      "id": "46",

      "name": "eMailAddress",

      "privacyUsagePurpose": "ADMIN",

      "description": "this is the email address privacy attributes for external ADMIN purposes",

      "privacyType": "External Purpose",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "UnAuthorized",

          "validityDuration": "Always"

        }

      ],

      "relatedRole": [

        {

          "role": "Administrator"

        }

      ]

    },

    { // Internal Retention example

      "id": "47",

      "name": "eMailAddress",

      "description": "this is the internal retention privacy rule for email address",

      "privacyType": "Internal Retention",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "Indefinitly",

          "validityDuration": "Always"

        }

      ]

    },

    { // External Retention example

      "id": "48",

      "name": "eMailAddress",

      "description": "this is the external retention privacy rule for email address",

      "privacyType": "External Retention",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "string",

          "default": true,

          "value": "No-retention",

          "validityDuration": "Always"

        }

      ]

    },

    { // choice of Internal Retention example

      "id": "49",

      "name": "Invoice Amount",

      "description": "this is the retention privacy rule for invoice amount",

      "privacyType": "Internal Retention",

      "criticalityLevel": "low",

      "validFor": {

        "startDateTime": "2013-04-19T16:42:23-04:00",

        "endDateTime": ""

      },

      "partyPrivacyProfileTypeCharValue": [

        {

          "valueType": "numeric",

          "default": true,

          "unitOfMeasure": "Year",

          "value": "15",

          "validityDuration": "Always"

        },

        {

          "valueType": "numeric",

          "default": false,

          "unitOfMeasure": "Year",

          "fromValue": "10",

          "toValue": "20",

          "rangeInterval": "1",

          "validityDuration": "Always"

        }

      ]

    }

  ]

}

 

Field Descriptions :

ApplicableRole: defines for which Roles the Party Privacy Profile Type is applicable.

Field

Description

r ole

Name of the role

 


Party Privacy Profile Type: represents a description for Party Privacy Profiles.

Field

Description

description

Description of the privacy profile type

href

Reference URL of the privacy profile type

id

Unique identifier for the privacy profile type

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status (In Design, Active, Rejected, Retired)

name

Name of the privacy profile type

validFor

The period for which the privacy profile type is valid

version

Privacy profile type version

 

PartyPrivacyProfileTypeCharacteristic: represents the Characteristics concerned by the Party Privacy Profile Type.

Field

Description

criticalityLevel

Level of criticality for the set of personal identifiable information

description

Description of the profile type characteristic

id

Index of the profile type characteristic in the list

name

Name of the characteristic (makes the link with the characteristic specification)

partyPrivacyProfileTypeCharValue

Possible privacy rules for the characteristic

privacyType

Type of privacy (e.g. Internal Purpose, External Purpose, Internal Retention, External Retention)

privacyUsagePurpose

Defines the “Purpose” authorized or refused for the characteristic (e.g. ADMIN, INFORMATION, MARKETING, RESEARCH, …)

relatedRole

Name of the roles for which the profile type characteristic is defined

validFor

The period for which the profile type characteristic is valid

 

PartyPrivacyProfileTypeCharValue: defines a possible Privacy rule for a Characteristic.

Field

Description

default

If true, indicates that is the default privacy rule

fromValue

Lower value for a customizable numeric value type

rangeInterval

Range interval for a customizable numeric value type

toValue

Upper value for a customizable numeric value type

unitOfMeasure

Unit of measure for a numeric value type

validityDuration

Duration of validity

value

Value of the privacy rule (e.g. Authorized, Unauthorized, No-retention, …)

valueType

Type of the value

 

RelatedParty: defines Party or Party Role linked to a specific entity; those who manage the Party Privacy Profile Type.

Field

Description

id

Unique identifier of the related party

href

Reference URL of the related party, could be a party reference or a party role reference

name

Name of the related party

r ole

Role of the related party

UML Model:

Lifecycle:

The Party Privacy Profile Type lifecycle is tracked using the lifecycleStatus field. The typical lifecycle values that can be taken are: In Design, Active, Rejected and Retired. The state machine specifying the typical state change transitions is provided below.

 

PARTY PRIVACY PROFILE Resource

A Party Privacy Profile represents the set of Privacy settings defined for a Party.

JSON representation of a Party Privacy Profile:

{

  "href": "http://serverlocation:port/privacyManagement/partyPrivacyProfile/394",

  "id": "394",

  "name": "John Doe's Privacy Profile",

  "description": "This is John Does Privacy profile",

  "dateCreated": "2016-03-16T15:15:51.209Z",

  "status": "agreed",

  "validFor": {

    "startDateTime": "2016-03-16T15:15:51.209Z",

    "endDateTime": ""

  },

  "agreedByParty": {

    "id": "2345",

    "href": "http://serverLocation:port/partyManagement/individual/2345",

    "role": "Customer",

    "name": "John Doe"

  },

  "partyPrivacyProfileType": {

    "id": "103",

    "href": "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103"

  },

  "partyPrivacyProfileCharValue": [

    {

      "name": "eMailAddress",

      "privacyUsagePurpose": "ADMIN",

      "value": "Authorized",

      "validFor": {

        "startDateTime": "2016-03-16T15:15:51.209Z",

        "endDateTime": ""

      },

      "relatedParty": [

        {

          "id": "10",

          "href": "http://serverLocation:port/partyManagement/organization/10",

          "role": "Administrator",

          "name": "Orange"

        }

      ]

    },

    {

      "name": "eMailAddress",

      "privacyUsagePurpose": "INFORMATION",

      "value": "Authorized",

      "validFor": {

        "startDateTime": "2016-03-16T15:15:51.209Z",

        "endDateTime": ""

      },

      "relatedParty": [

        {

          "id": "11",

          "href": "http://serverLocation:port/partyManagement/individual/11",

          "role": "Vendor",

          "name": "Alice"

        },

        {

          "id": "12",

          "href": "http://serverLocation:port/partyManagement/individual/12",

          "role": "Employee",

          "name": "Bob"

        }

      ]

    },

    {

      "name": "eMailAddress",

      "privacyUsagePurpose": "MARKETING",

      "value": "Authorized",

      "validFor": {

        "startDateTime": "2016-03-16T15:15:51.209Z",

        "endDateTime": "2016-06-16T15:15:51.209Z"

      },

      "relatedParty": [

        {

          "id": "11",

          "href": "http://serverLocation:port/partyManagement/individual/11",

          "role": "Vendor",

          "name": "Alice"

        }

      ],

      "characteristicAgreement": {

        "id": "6810",

        "href": "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810"

      }

    },

    {

      "name": "eMailAddress",

      "privacyUsagePurpose": "RESEARCH",

      "value": "Unauthorized",

      "validFor": {

        "startDateTime": "2016-03-16T15:15:51.209Z",

        "endDateTime": ""

      },

      "relatedParty": [

        {

          "id": "12",

          "href": "http://serverLocation:port/partyManagement/individual/12",

          "role": "Employee",

          "name": "Bob"

        }

      ]

    }

  ],

  "agreement": {

    "id": "6810",

    "href": "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810",

    "type": "commercial"

  }

}

 

Field Descriptions :

AgreedByParty: defines the Party or Party Role who has agreed the Party Privacy Profile.

Field

Description

id

Unique identifier of related party

href

Reference URL of the related party, could be a party reference or a party role reference

role

Role of the related party

name

Name of the related party

 

Agreement: describes the Party Privacy Agreement linked to this Party Privacy Profile.

Field

Description

id

Unique identifier of the agreement

href

Reference URL of the agreement

type

The type of the agreement. For example “commercial”

 

Party Privacy Profile: represents the privacy choices made by a Party Role.

Field

Description

description

Description of the privacy profile

href

Reference URL of the privacy profile

id

Unique identifier for the privacy profile

dateCreated

Date and time of creation of the privacy profile

status

Current status of the privacy profile (Created, Terminated, …)

name

Name of the privacy profile

validFor

The period for which the privacy profile is valid

 

PartyPrivacyProfileCharValue: represents the Privacy rules chosen for this Party Privacy Profile.

Field

Description

characteristicAgreement

The privacy agreement linked to the characteristic if it has a high criticality level

name

Name of the characteristic

privacyUsagePurpose

Defines the “Purpose” authorized or refused for the characteristic (e.g. ADMIN, INFORMATION, MARKETING, RESEARCH, …)

relatedParty

Reference to a party or party role for which the privacy rule is defined

validFor

The period for which the privacy rule is valid

value

Value of the privacy rule

 

Party Privacy Profile Type: represents a reference to the instantiated Party Privacy Profile Type.

Field

Description

href

Reference URL of the privacy profile type

id

Unique identifier for the privacy profile type

 

UML Model:

Lifecycle:

The Party Privacy Profile lifecycle is tracked using the status field. The typical lifecycle values that can be taken are: Created, Terminated. The state machine specifying the typical state change transitions is provided below.

 

PARTY PRIVACY Agreement Resource

A Party Privacy Agreement represents the approval made by the Party about a Party Privacy Profile.

JSON representation of a Party Privacy Agreement:

{

  "href": "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810",

  "id": "6810",

  "agreementPeriod": {

    "startDateTime": "2016-03-16T15:15:51.209Z",

    "endDateTime": "2016-09-16T15:15:51.209Z"

  },

  "completionDate": "2016-10-16",

  "description": "This agreement …",

  "documentNumber": 13,

  "initialDate": "2016-03-16T15:15:51.210Z",

  "name": "Customer mass market privacy agreement",

  "statementOfIntent": "Agreement on customer mass market privacy profile",

  "status": "validated",

  "type": "commercial",

  "version": "1",

  "agreementSpecification": {

    "description": "This agreement specification defines the rules of privacy to be followed by each party",

    "href": "http://serverlocation:port/privacyManagement/partyPrivacyAgreementSpecification/8139",

    "id": "8139",

    "name": "General Agreement Specification"

  },

  "agreementItem": [

    {

      "productOffering": [

        {

          "href": "https://host:port/productOffering/productOffering/9559",
          "id": "9559",
          "name": "Privacy Service",
          "bundledProductOffering": [
            {
              "href": "https://host:port/productOffering/bundledProductOffering/7120",
              "id": "7120",
              "name": "Magic Offer",
              "bundledProductOffering": []
            }
          ]

        }

      ],

      "termOrCondition": [

        {

          "description": "This agreement term or condition …",

          "id": "8905",

          "validFor": {

            "startDateTime": "2016-03-16T15:15:51.211Z",

            "endDateTime": "2016-09-16T15:15:51.211Z"           

          }

        }

      ]

    }

  ],

  "engagedPartyRole": [

    {

      "href": "http://serverLocation:port/partyManagement/partyRole/1",

      "id": "1",

      "name": "Customer",

      "partyId": "2345",

      "partyName": "John Doe"

    }

  ],

  "agreementAuthorization": [

    {

      "date": "2016-03-16T15:15:51.211Z",

      "signatureRepresentation": "Digital",

      "state": "approved"

    }

  ],

  "characteristic": [

    {

      "name": "country",

      "value": "France"

    }

  ],

  "associatedAgreement": [

    {

      "href": "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/987654",

      "id": "987654",

      "name": "General Privacy Agreement"

    }

  ],

  "partyPrivacyProfile": [

    "href": "http://serverlocation:port/privacyManagement/partyPrivacyProfile/394",

    "href": "http://serverlocation:port/privacyManagement/partyPrivacyProfile/1312"

  ],

  "partyPrivacyProfileCharValue": [

    {

      "name": "eMailAddress",

      "privacyUsagePurpose": "MARKETING",

      "value": "Authorized",

      "validFor": {

        "startDateTime": "2016-03-16T15:15:51.211Z",

        "endDateTime": "2016-06-16T15:15:51.211Z"

      },

      "relatedParty": [

        {

          "id": "11",

          "href": "http ://serverLocation:port/partyManagement/partyRole/11",

          "role": "Vendor",

          "name": "Alice"

        }

      ]

    }

  ]

}

 

Field Descriptions :

Agreement: represents the approval made by the Engaged Party about a Party Privacy Profile.

Field

Description

agreementPeriod

The time period during which the agreement is in effect

completionDate

Date at which the agreement is completed

description

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

documentNumber

A reference number assigned to an agreement that follows a prescribed numbering system

href

Unique URL identifying the agreement as a resource

id

Unique identifier for the agreement

initialDate

Date at which the agreement was initialized

name

A human-readable name for the agreement

statementOfIntent

An overview and goals of the agreement

status

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

type

The type of the agreement. For example “commercial”

version

A string identifying the version of the agreement

 

AgreementAuthorization: represents a business participant that is responsible for approving the Agreement.

Field

Description

date

The date associated with the authorization state

signatureRepresentation

Indication that represents whether the signature is a physical paper signature or a digital signature

state

Current status of the authorization, for example in process, approved, rejected

 

AgreementItem: represents a part of the Agreement expressed in terms of a product offering and possibly including specific terms and conditions.

Field

Description

productOffering

A list of product offering references

termOrCondition

The term or condition of the agreement

 

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

Field

Description

description

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

href

Reference URL of the agreement specification

id

Unique identifier of the agreement specification

name

Name of the agreement specification

 

AssociatedAgreement: references another related Agreement.

Field

Description

href

Reference URL of the agreement

id

Identifier of the agreement

name

Name of the agreement

 


Characteristic: describes a given characteristic of an object or entity through a name/value pair.

Field

Description

name

Name of the characteristic

value

Value of the characteristic

 

EngagedPartyRole: defines the Party or Party Role involved in the Agreement.

Field

Description

href

Reference URL of the referred party role

id

Unique identifier of referred party role

name

The name of the referred party role

partyId

The identifier of the engaged party that is linked to the PartyRole object

partyName

The name of the engaged party that is linked to the PartyRole object

 

Party Privacy Profile: represents the set of Privacy settings defined for a Party.

Field

Description

href

Reference URL of the agreed party privacy profile

 

PartyPrivacyProfileCharValue: represents a high criticality Characteristic whose chosen Privacy rules is included in the Agreement.

Field

Description

name

Name of the characteristic

privacyUsagePurpose

Defines the “Purpose” authorized or refused for the characteristic (e.g. ADMIN, INFORMATION, MARKETING, RESEARCH, …)

relatedParty

Reference to a party or party role for which the privacy rule is defined

validFor

The period for which the privacy rule is valid

value

Value of the privacy rule

 


UML Model:

Lifecycle:

The Agreement lifecycle is tracked using the status field. The typical lifecycle values that can be taken are: Initialized, In process, Pending Update, Validated and Rejected. The state machine specifying the typical state change transitions is provided below.

 

Export Job Resource

An ExportJob resource represents a TASK used to export resources to a File

The ExportJob resource supports the following properties:

Attribute name

Description

query

Used to scope the exported data (identical to GET filter construct using target ID as base)

“query”: ”type=productOffering&version=2.0”

path

URL of the root resource acting as the source for streaming content to the file specified by the ExportJob

../privacyManagement/partyPrivacyProfile

content-type

The format of the exported data . By default “application/json”

status

notstarted, running, succeeded, failed

url

URL of the File containing the data to be exported

a file URL, which is of the form

file://host/path

where host is the fully qualified domain name of the system on which the path is accessible, and path is a hierarchical directory path of the form directory/directory/.../name

completionDate

Date at which the Job was completed.

creationDate

Date at which the Job was created.

errorLog

Reason for Failure

 

JSON representation of an ExportJob

{
        "id" : "54" ,
        "href" : "http:/api/privacManagement/exportJob/54" ,
        "status" : "running" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacy/54"
    }    

 

UML Model:

 

Import Job Resource

An ImportJob resource represent a TASK used to import resources from a File

The ImportJob resource supports the following properties:

Attribute name

Description

content-type

The format of the imported data . By default “application/json”

path

URL of the root resource where the content of the file specified by the ImportJob must be applied

../privacyManagement/partyPrivacyProfile

status

notstarted, running, succeeded, failed

url

URL of the File containing the data to be imported

a file URL, which is of the form

file://host/path

where host is the fully qualified domain name of the system on which the path is accessible, and path is a hierarchical directory path of the form directory/directory/.../name

 

completionDate

Date at which the Job was completed.

creationDate

Date at which the Job was created.

errorLog

            Reason for Failure if status is failed

 

JSON representation of an ImportJob

{
        "id" : "54" ,
        "href" : "http:/api/ privacyManagement/importJob/54" ,
        "status" : "completed" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacy/54"
    }    

 

UML Model:


Notification Resource Models

11 notification event types are defined :

  1. PartyPrivacyProfileTypeCreateNotification
  2. PartyPrivacyProfileTypeNotification
  3. PartyPrivacyProfileTypeDeleteNotification
  4. PartyPrivacyProfileCreateNotification
  5. PartyPrivacyProfileUpdateNotification
  6. PartyPrivacyProfileDeleteNotification
  7. PartyPrivacyAgreementCreateNotification
  8. PartyPrivacyAgreementUpdateNotification
  9. PartyPrivacyAgreementDeleteNotification
  10. ImportJobCompletionNotification
  11. ExportJobCompletionNotification

 

PARTY PRIVACY PROFILE TYPE Notifications

  1. Create
  2. Update
  3. Delete

UML Model:

 

 

Event: PartyPrivacyProfileTypeCreateNotification

{

"eventType" : "PartyPrivacyProfileTypeCreateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1154231" ,

"event" : {

"partyPrivacyProfileType" :

{

"id" : "12" ,

            Following a whole representation of the Party Privacy Profile Type with all its attributes
            See Party Privacy Profile Type Resource.

}

}

}

 

Event: PartyPrivacyProfileTypeUpdateNotification

{

"eventType" : "PartyPrivacyProfileTypeUpdateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "119331" ,

"event" : {

"partyPrivacyProfileType" :

{

"id" : "12" ,

            Following a whole representation of the Party Privacy Profile Type with all its attributes
            See Party Privacy Profile Type Resource.

}

}

}

 

Event: PartyPrivacyProfileTypeDeleteNotification

{

"eventType" : "PartyPrivacyProfileTypeDeleteNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1189231" ,

"event" : {

"partyPrivacyProfileType" :

{

"id" : "12" ,

            Following a whole representation of the Party Privacy Profile Type with all its attributes
            See Party Privacy Profile Type Resource.

}

}

}

 

PARTY PRIVACY PROFILE Notifications

  1. Create
  2. Update
  3. Delete

UML Model:

 

 

Event: PartyPrivacyProfileCreateNotification

{

"eventType" : "PartyPrivacyProfileCreateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1154391" ,

"event" : {

"partyPrivacyProfile" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Profile with all its attributes
            See Party Privacy Profile Resource.

}

}

}

 

Event: PartyPrivacyProfileUpdateNotification

{

"eventType" : "PartyPrivacyProfileUpdateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1156731" ,

"event" : {

"partyPrivacyProfile" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Profile with all its attributes
            See Party Privacy Profile Resource.

}

}

}

 

Event: PartyPrivacyProfileDeleteNotification

{

"eventType" : "PartyPrivacyProfileDeleteNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1154278" ,

"event" : {

"partyPrivacyProfile" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Profile with all its attributes
            See Party Privacy Profile Resource.

}

}

}

 

PARTY PRIVACY AGREEMENT Notifications

  1. Create
  2. Update
  3. Delete

UML Model:

 

Event: PartyPrivacyAgreementCreateNotification

{

"eventType" : "PartyPrivacyAgreementCreateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1154391" ,

"event" : {

"partyPrivacyAgreement" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Agreement with all its attributes
            See Party Privacy Agreement Resource.

}

}

}

 

Event: PartyPrivacyAgreementUpdateNotification

{

"eventType" : "PartyPrivacyAgreementUpdateNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1156731" ,

"event" : {

"partyPrivacyAgreement" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Agreement with all its attributes
            See Party Privacy Agreement Resource.

}

}

}

 

Event: PartyPrivacyAgreementDeleteNotification

{

"eventType" : "PartyPrivacyAgreementDeleteNotification" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1154278" ,

"event" : {

"partyPrivacyAgreement" :

{

"id" : "128" ,

            Following a whole representation of the Party Privacy Agreement with all its attributes
            See Party Privacy Agreement Resource.

}

}

}

 

Export and Import Job Notifications

  1. Export Job Completion Notification
  2. Import Job Completion Notification

UML Model:

 

Event: ExportJobCompletionNotification

{
    "eventType" : "ExportJobCompletionNotification" ,
    "eventTime" : "2014-09-27T05:46:25.0Z" ,
    "eventId" : "1154278" ,
    "event" : { "exportJob" : {
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/exportJob/54" ,
        "status" : "succeeded" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacyManagement/54.json"
    }}
}

 

Event: ImportJobCompletionNotification

{
    "eventType" : "ImportJobCompletionNotification" ,
    "eventTime" : "2014-09-27T05:46:25.0Z" ,
    "eventId" : "1154278" ,
    "event" : { "importJob" : {
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/importJob/54" ,
        "status" : "succeeded" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacyManagement/54.json"
    }}
}

 


  API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST requests and responses.

Remember that the following Uniform Contract rules must be used:

 

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

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to 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.

 

 

GET /privacyManagement/partyPrivacyProfileType/{ID}

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}

Description :

  • Operation to retrieve privacy profile types in a privacy repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri

 

Behavior :

  • Standard behavior and response codes for GET operations

Example : Retrieve privacy profile type with id 103 - with all its attributes.

REQUEST

GET /privacyManagement/partyPrivacyProfileType/103

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

{

  "id" : "103" ,

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103" ,

  "version" : "1.0" ,

  "lastUpdate" : "2013-04-19T16:42:23-04:00" ,

  "name" : "Customer Mass Market Privacy" ,

  "description" : "This is the customer mass market privacy" ,

  "lifecycleStatus" : "active" ,

  "validFor" : {

    "startDateTime" : "2013-04-19T16:42:23-04:00" ,

    "endDateTime" : "2013-06-19T00:00:00-04:00"

  },

  "relatedParty" : [

    {

      "id" : "1066" ,

      "href" : "http://serverlocation:port/partyManagement/individual/1066" ,

      "role" : "Profile Type Admin" ,

      "name" : "James Smith"

    }

  ],

  "applicableRole" : [

    {

      "role" : "Customer"

    }

  ],

  "partyPrivacyProfileTypeCharacteristic" : [

    { // ALWAYS example

      "id" : "42" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy for internal ADMIN purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]     

    },

    { // OPT-OUT example

      "id" : "43" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "description" : "this is the email address privacy attributes for internal INFORMATION purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        },

        {

          "role" : "Employee"

        }

      ]

    },

    { // OPT-IN example

      "id" : "44" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "description" : "this is the email address privacy attributes for internal MARKETING purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "high" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Authorized" ,

          "validityDuration" : "3 months"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        }

      ]

    },

    { // NEVER example

      "id" : "45" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "description" : "this is the email address privacy attributes for internal RESEARCH purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Employee"

        }

      ]

    },

    { // External purpose example

      "id" : "46" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy attributes for external ADMIN purposes" ,

      "privacyType" : "External Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "UnAuthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]

    },

    { // Internal Retention example

      "id" : "47" ,

      "name" : "eMailAddress" ,

      "description" : "this is the internal retention privacy rule for email address" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Indefinitly" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // External Retention example

      "id" : "48" ,

      "name" : "eMailAddress" ,

      "description" : "this is the external retention privacy rule for email address" ,

      "privacyType" : "External Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "No-retention" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // choice of Internal Retention example

      "id" : "49" ,

      "name" : "Invoice Amount" ,

      "description" : "this is the retention privacy rule for invoice amount" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "numeric" ,

          "default" : true,

          "unitOfMeasure" : "Year" ,

          "value" : "15" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "numeric" ,

          "default" : false,

          "unitOfMeasure" : "Year" ,

          "fromValue" : "10" ,

          "toValue" : "20" ,

          "rangeInterval" : "1" ,

          "validityDuration" : "Always"

        }

      ]

    }

  ]

}

 

Example : Retrieve Customer Mass Market Privacy individual entry and we only want to get its name.

REQUEST

GET /privacyManagement/partyPrivacyProfileType/103?fields=name

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

{

    "name" : "Customer Mass Market Privacy"

}

 

GET /privacyManagement/partyPrivacyProfile/{ID}

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}

Description :

  • Operation to retrieve privacy profiles in a privacy repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri

Behavior :

  • Standard behavior and response codes for GET operations

Example : Get the name of all privacy profiles instantiating a given privacy profile type (103)

REQUEST

GET /privacyManagement/partyPrivacyProfile?fields=name&partyPrivacyProfileType.id=103

Accept: application/json

RESPONSE

200

Content-Type: application/json

[

    {

        "id" : "394" ,

        "name" : "John Doe’s Privacy Profile"

    },

    {

        "id" : "1312" ,

        "name" : "Jane Doe’s Privacy Profile"

    }

]

 

Example : Get a specific privacy profile using its id, returning all attributes

REQUEST

GET /privacyManagement/partyPrivacyProfile/394

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

{

  "id" : "394" ,

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfile/394" ,

  "name" : "John Doe's Privacy Profile" ,

  "description" : "This is John Does Privacy profile" ,

  "dateCreated" : "2016-03-16T15:15:51.209Z" ,

  "status" : "agreed" ,

  "validFor" : {

    "startDateTime" : "2016-03-16T15:15:51.209Z" ,

    "endDateTime" : ""

  },

  "agreedByParty" : {

    "id" : "2345" ,

    "href" : "http ://serverLocation:port/partyManagement/individual/2345" ,

    "role" : "Customer" ,

    "name" : "John Doe"

  },

  "partyPrivacyProfileType" : {

    "id" : "103" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103"

  },

  "partyPrivacyProfileCharValue" : [

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "10" ,

          "href" : "http ://serverLocation:port/partyManagement/organization/10" ,

          "role" : "Administrator" ,

          "name" : "Orange"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        },

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : "2016-06-16T15:15:51.209Z"

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        }

      ],

      "characteristicAgreement" : {

        "id" : "6810" ,

        "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810"

      }

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "value" : "Unauthorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    }

  ],

  "agreement" : {

    "id" : "6810" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810" ,

    "type" : "commercial"

  }

}

 

GET /privacyManagement/partyPrivacyAgreement/{ID}

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}

Description :

  • Operation to retrieve privacy agreements in a privacy repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri

Behavior :

  • Standard behavior and response codes for GET operations

Example : Get a privacy agreement by its id

REQUEST

GET /privacyManagement/partyPrivacyAgreement/6810

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

{

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810" ,

  "id" : "6810" ,

  "agreementPeriod" : {

    "startDateTime" : "2016-03-16T15:15:51.209Z" ,

    "endDateTime" : "2016-09-16T15:15:51.209Z"

  },

  "completionDate" : "2016-10-16" ,

  "description" : "This agreement …" ,

  "documentNumber" : 13,

  "initialDate" : "2016-03-16T15:15:51.210Z" ,

  "name" : "Customer mass market privacy agreement" ,

  "statementOfIntent" : "Agreement on customer mass market privacy profile" ,

  "status" : "validated" ,

  "type" : "commercial" ,

  "version" : "1" ,

  "agreementSpecification" : {

    "description" : "This agreement specification defines the rules of privacy to be followed by each party" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreementSpecification/8139" ,

    "id" : "8139" ,

    "name" : "General Agreement Specification"

  },

  "agreementItem" : [

    {

      "productOffering" : [

        {

          "href" : "https://host:port/productOffering/productOffering/9559" ,
          "id" : "9559" ,
          "name" : "Privacy Service" ,
          "bundledProductOffering" : [
            {
              "href" : "https://host:port/productOffering/bundledProductOffering/7120" ,
              "id" : "7120" ,
              "name" : "Magic Offer" ,
              "bundledProductOffering" : []
            }
          ]

        }

      ],

      "termOrCondition" : [

        {

          "description" : "This agreement term or condition …" ,

          "id" : "8905" ,

          "validFor" : {

            "startDateTime" : "2016-03-16T15:15:51.211Z" ,

            "endDateTime" : "2016-09-16T15:15:51.211Z"            

          }

        }

      ]

    }

  ],

  "engagedPartyRole" : [

    {

      "href" : "http://serverLocation:port/partyManagement/partyRole/1" ,

      "id" : "1" ,

      "name" : "Customer" ,

      "partyId" : "2345" ,

      "partyName" : "John Doe"

    }

  ],

  "agreementAuthorization" : [

    {

      "date" : "2016-03-16T15:15:51.211Z" ,

      "signatureRepresentation" : "Digital" ,

      "state" : "approved"

    }

  ],

  "characteristic" : [

    {

      "name" : "country" ,

      "value" : "France"

    }

  ],

  "associatedAgreement" : [

    {

      "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/987654" ,

      "id" : "987654" ,

      "name" : "General Privacy Agreement"

    }

  ],

  "partyPrivacyProfile" : [

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfile/394" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfile/1312"

  ],

  "partyPrivacyProfileCharValue" : [

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.211Z" ,

        "endDateTime" : "2016-06-16T15:15:51.211Z"

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/partyRole/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        }

      ]

    }

  ]

}

 

PATCH /privacyManagement/partyPrivacyProfileType/{ID}

This Uniform Contract operation is used to partially update the representation of a privacy profile type.

Description :

  • Patch operation can be used partially update one or more privacy profile types
  • The resource represents a managed entity or a collection
  • The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior :

  • Return Status Codes:
    • Returns HTTP/1.1 status code 201 if privacy profile type was updated successfully
    • 400 - Bad Request Error
    • 404 - If no record was found for the supplied criteria
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

 

Patchable attributes for a privacy profile type:

Attribute name

Patchable

Rule

id

N

 

version

Y

 

lastUpdate

Y

 

name

Y

 

description

Y

 

lifecycleStatus

Y

 

validFor

Y

 

relatedParty

Y

 

applicableRole

Y

 

partyPrivacyProfileTypeCharacteristic

Y

 

 

Further document any rules that must be implemented when patching attributes.

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

relatedParty

role and party are mandatory

applicableRole

role is mandatory

partyPrivacyProfileTypeCharacteristic

a default partyPrivacyProfileCharValue is mandatory

 

Example : Update the lifecycle status of the Customer Mass Market Privacy (identified with ‘103’).

REQUEST

PATCH privacyManagement/ partyPrivacyProfileType/103

Content-type: application/json

{

    "lifecycleStatus" : "Retired"

}

RESPONSE

201

Content-Type: application/json

 

{

  JSON resource representation with all attributes including the changed one

  See Party Privacy Profile Type resource model for details

}

 

Example : Update Customer Mass Market Privacy (identified with ‘103’): it is related to a Party or Party Role that is already stored in the party referential.

REQUEST

PATCH privacyManagement/ partyPrivacyProfileType/103

Content-type: application/json-patch+json

{

"op" : "add" ,

"path" : "/relatedParty" ,

"value" : {

"id" : "1070" ,

"href" : "http://serverlocation:port/partyManagement/individual/1070" ,

"role" : "Profile Type Admin" ,

"name" : "Edward Miller"

}

}

RESPONSE

201

Content-Type: application/json

 

{  JSON resource representation with all attributes including the changed one

  See Party Privacy Profile Type resource model for details

}

 

PATCH /privacyManagement/partyPrivacyProfile/{ID}

This Uniform Contract operation is used to partially update the representation of a privacy profile.

Description :

  • Patch operation can be used partially update one or more privacy profiles
  • The resource represents a managed entity or a collection
  • The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior :

  • Return Status Codes:
    • Returns HTTP/1.1 status code 201 if privacy profile was updated successfully
    • 400 - Bad Request Error
    • 404 - If no record was found for the supplied criteria
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

 

Patchable attributes for a privacy profile:

Attribute name

Patchable

Rule

id

N

 

name

Y

 

description

Y

 

dateCreated

N

 

status

Y

 

validFor

Y

 

agreedByParty

N

 

partyPrivacyProfileType

N

 

partyPrivacyProfileCharValue

Y

 

agreement

Y

 

 

Further document any rules that must be implemented when patching attributes.

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

partyPrivacyProfileCharValue

value must be one of the possibilities described in the referenced profile type

agreement

Reference must be set

 

Example : Update the John Doe’s privacy profile (identified with ‘394’) to tag it as terminated.

 

REQUEST

PATCH privacyManagement/ partyPrivacyProfile/394

Content-type: application/json

{

"id" : "394" ,

"href" : " http://serverlocation:port/privacyManagement/partyPrivacyProfile/394" ,

"status" : "Terminated" ,

"validFor" : {

"endDateTime" : "2016-04-19T16:42:23-04:00"

}

}

RESPONSE

201

Content-Type: application/json

 

{

  JSON resource representation with all attributes including the changed one

  See Party Privacy Profile resource model for details

}

 

 

Example : Update the “eMailAddress for ADMIN purpose” Characteristic Value of the John Doe’s privacy profile (identified with ‘394’).

 

REQUEST

PATCH privacyManagement/ partyPrivacyProfile/394

Content-type: application/json-patch+json

[

{

"op" : "replace" ,

"path" : "/partyPrivacyProfileCharValue/0" ,

"value" : {

"name" : "eMailAddress" ,

"privacyUsagePurpose" : "ADMIN" ,

"value" : "Authorized" ,

"validFor" : {

"startDateTime" : "2016-03-16T15:15:51.209Z" ,

"endDateTime" : "2016-04-19T16:42:23.100Z"

},

"relatedParty" : [

{

"id" : "10" ,

"href" : "http ://serverLocation:port/partyManagement/organization/10" ,

"role" : "Administrator" ,

"name" : "Orange"

}

]

}

}, {

"op" : "add" ,

"path" : "/partyPrivacyProfileCharValue" ,

"value" : {

"name" : "eMailAddress" ,

"privacyUsagePurpose" : "ADMIN" ,

"value" : "Unauthorized" ,

"validFor" : {

"startDateTime" : "2016-04-19T16:42:23.100Z" ,

"endDateTime" : ""

}

}

}

]

RESPONSE

201

Content-Type: application/json

 

{

  JSON resource representation with all attributes including the changed one

  See Party Privacy Profile resource model for details

}

 

PATCH /privacyManagement/partyPrivacyAgreement/{ID}

This Uniform Contract operation is used to partially update the representation of a privacy agreement.

Description :

  • Patch operation can be used partially update one or more privacy agreements
  • The resource represents a managed entity or a collection
  • The identifier is a string that can consist of numbers, not necessarily alphanumeric

Behavior :

  • Return Status Codes:
    • Returns HTTP/1.1 status code 201 if privacy profile was updated successfully
    • 400 - Bad Request Error
    • 404 - If no record was found for the supplied criteria
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

 

Patchable attributes for a privacy profile:

Attribute name

Patchable

Rule

id

N

 

agreementPeriod

Y

 

completionDate

N

 

description

Y

 

documentNumber

Y

 

initialDate

Y

 

name

Y

 

statementOfIntent

Y

 

status

Y

 

type

Y

 

version

Y

 

agreementSpecification

Y

 

agreementItem

Y

 

engagedPartyRole

Y

 

agreementAuthorization

Y

 

characteristic

Y

 

associatedAgreement

Y

 

partyPrivacyProfile

Y

 

partyPrivacyProfileCharValue

Y

 

 

Further document any rules that must be implemented when patching attributes.

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

engagedPartyRole

id and name are mandatory

associatedAgreement

id and href are mandatory

 

Example : Changing the status of the agreement as rejected .

 

REQUEST

PATCH privacyManagement/ partyPrivacyAgreement/6810

Content-type: application/json-patch+json

[

{

"op" : "replace" ,

"path" : "/status" ,

"value" : "rejected"

}

]

RESPONSE

201

Content-Type: application/json

 

{

  JSON resource representation with all attributes including the changed one

  See Party Privacy Agreement resource model for details

}

 

 

POST /privacyManagement/partyPrivacyProfileType

This operation is used to create a privacy profile type.

  • The identifier is a string that can consist of numbers, not necessarily alphanumeric
  • The mandatory element(s) is/are
    • partyPrivacyProfileTypeCharacteristic

When using following elements there are some mandatory attributes within each element:

  • Within “relatedParty”
    • role
    • href
  • Within “applicableRole”
    • role
  • Within “partyPrivacyProfileTypeCharacteristic”
    • name
    • privacyUUsagePurpose
    • partyPrivacyProfileTypeCharValue
  • The id is generated automatically

Behavior :

  • Return Status Codes:
    • 201 - privacy profile type was created successfully
    • 400 - Bad Request Error
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

 

Attribute name

Mandatory

Default

Rule

id

N

Automatically generated

If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used

version

N

0

 

lastUpdate

N

Current date

 

name

N

 

 

description

N

 

 

lifecycleStatus

N

In Design

 

validFor

N

 

 

relatedParty

N

 

 

applicableRole

N

 

 

partyPrivacyProfileTypeCharacteristic

Y

 

 

 

Further specify any rules on the creation of the entity

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

relatedParty

role and party are mandatory

applicableRole

role is mandatory

partyPrivacyProfileTypeCharacteristic

a default partyPrivacyProfileCharValue is mandatory

 

Example : creation of a privacy profile type named Customer Mass Market Privacy

REQUEST

POST privacyManagement/partyPrivacyProfileType

Content-type: application/json

 

{

  "version" : "1.0" ,

  "lastUpdate" : "2013-04-19T16:42:23-04:00" ,

  "name" : "Customer Mass Market Privacy" ,

  "description" : "This is the customer mass market privacy" ,

  "lifecycleStatus" : "active" ,

  "validFor" : {

    "startDateTime" : "2013-04-19T16:42:23-04:00" ,

    "endDateTime" : "2013-06-19T00:00:00-04:00"

  },

  "relatedParty" : [

    {

      "id" : "1066" ,

      "href" : "http://serverlocation:port/partyManagement/individual/1066" ,

      "role" : "Profile Type Admin" ,

      "name" : "James Smith"

    }

  ],

  "applicableRole" : [

    {

      "role" : "Customer"

    }

  ],

  "partyPrivacyProfileTypeCharacteristic" : [

    { // ALWAYS example

      "id" : "42" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy for internal ADMIN purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]     

    },

    { // OPT-OUT example

      "id" : "43" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "description" : "this is the email address privacy attributes for internal INFORMATION purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        },

        {

          "role" : "Employee"

        }

      ]

    },

    { // OPT-IN example

      "id" : "44" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "description" : "this is the email address privacy attributes for internal MARKETING purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "high" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Authorized" ,

          "validityDuration" : "3 months"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        }

      ]

    },

    { // NEVER example

      "id" : "45" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "description" : "this is the email address privacy attributes for internal RESEARCH purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Employee"

        }

      ]

    },

    { // External purpose example

      "id" : "46" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy attributes for external ADMIN purposes" ,

      "privacyType" : "External Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "UnAuthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]

    },

    { // Internal Retention example

      "id" : "47" ,

      "name" : "eMailAddress" ,

      "description" : "this is the internal retention privacy rule for email address" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Indefinitly" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // External Retention example

      "id" : "48" ,

      "name" : "eMailAddress" ,

      "description" : "this is the external retention privacy rule for email address" ,

      "privacyType" : "External Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "No-retention" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // choice of Internal Retention example

      "id" : "49" ,

      "name" : "Invoice Amount" ,

      "description" : "this is the retention privacy rule for invoice amount" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "numeric" ,

          "default" : true,

          "unitOfMeasure" : "Year" ,

          "value" : "15" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "numeric" ,

          "default" : false,

          "unitOfMeasure" : "Year" ,

          "fromValue" : "10" ,

          "toValue" : "20" ,

          "rangeInterval" : "1" ,

          "validityDuration" : "Always"

        }

      ]

    }

  ]

}

RESPONSE

201

Content-Type: application/json

 

{

  "id" : "103" ,

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103" ,

  "version" : "1.0" ,

  "lastUpdate" : "2013-04-19T16:42:23-04:00" ,

  "name" : "Customer Mass Market Privacy" ,

  "description" : "This is the customer mass market privacy" ,

  "lifecycleStatus" : "active" ,

  "validFor" : {

    "startDateTime" : "2013-04-19T16:42:23-04:00" ,

    "endDateTime" : "2013-06-19T00:00:00-04:00"

  },

  "relatedParty" : [

    {

      "id" : "1066" ,

      "href" : "http://serverlocation:port/partyManagement/individual/1066" ,

      "role" : "Profile Type Admin" ,

      "name" : "James Smith"

    }

  ],

  "applicableRole" : [

    {

      "role" : "Customer"

    }

  ],

  "partyPrivacyProfileTypeCharacteristic" : [

    { // ALWAYS example

      "id" : "42" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy for internal ADMIN purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]     

    },

    { // OPT-OUT example

      "id" : "43" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "description" : "this is the email address privacy attributes for internal INFORMATION purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Authorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        },

        {

          "role" : "Employee"

        }

      ]

    },

    { // OPT-IN example

      "id" : "44" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "description" : "this is the email address privacy attributes for internal MARKETING purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "high" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "string" ,

          "default" : false,

          "value" : "Authorized" ,

          "validityDuration" : "3 months"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Vendor"

        }

      ]

    },

    { // NEVER example

      "id" : "45" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "description" : "this is the email address privacy attributes for internal RESEARCH purpose" ,

      "privacyType" : "Internal Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Unauthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Employee"

        }

      ]

    },

    { // External purpose example

      "id" : "46" ,

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "description" : "this is the email address privacy attributes for external ADMIN purposes" ,

      "privacyType" : "External Purpose" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "UnAuthorized" ,

          "validityDuration" : "Always"

        }

      ],

      "relatedRole" : [

        {

          "role" : "Administrator"

        }

      ]

    },

    { // Internal Retention example

      "id" : "47" ,

      "name" : "eMailAddress" ,

      "description" : "this is the internal retention privacy rule for email address" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "Indefinitly" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // External Retention example

      "id" : "48" ,

      "name" : "eMailAddress" ,

      "description" : "this is the external retention privacy rule for email address" ,

      "privacyType" : "External Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "string" ,

          "default" : true,

          "value" : "No-retention" ,

          "validityDuration" : "Always"

        }

      ]

    },

    { // choice of Internal Retention example

      "id" : "49" ,

      "name" : "Invoice Amount" ,

      "description" : "this is the retention privacy rule for invoice amount" ,

      "privacyType" : "Internal Retention" ,

      "criticalityLevel" : "low" ,

      "validFor" : {

        "startDateTime" : "2013-04-19T16:42:23-04:00" ,

        "endDateTime" : ""

      },

      "partyPrivacyProfileTypeCharValue" : [

        {

          "valueType" : "numeric" ,

          "default" : true,

          "unitOfMeasure" : "Year" ,

          "value" : "15" ,

          "validityDuration" : "Always"

        },

        {

          "valueType" : "numeric" ,

          "default" : false,

          "unitOfMeasure" : "Year" ,

          "fromValue" : "10" ,

          "toValue" : "20" ,

          "rangeInterval" : "1" ,

          "validityDuration" : "Always"

        }

      ]

    }

  ]

}

 

POST /privacyManagement/partyPrivacyProfile

This operation is used to create a privacy profile.

  • The identifier is a string that can consist of numbers, not necessarily alphanumeric
  • The mandatory element(s) is/are:
    • agreedByParty
    • partyPrivacyProfileType
    • partyPrivacyProfileCharValue

When using following elements there are some mandatory attributes within each element:

  • Within “agreedByParty”
    • role
    • href
  • Within “partyPrivacyProfileType”
    • href
  • Within “partyPrivacyProfileCharValue”
    • name
    • privacyUsagePurpose
    • value
  • Within “agreement”
    • href
  • The id is generated automatically

Behavior :

  • Return Status Codes:
    • 201 – privacy profile was created successfully
    • 400 - Bad Request Error
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

Specify the attributes required when an entity is created (and their default values if not):

 

Attribute name

Mandatory

Default

Rule

id

N

Automatically generated

If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used

name

N

 

 

description

N

 

 

dateCreated

N

Current date

 

status

N

Created

 

validFor

N

 

 

agreedByParty

Y

 

 

partyPrivacyProfileType

Y

 

 

partyPrivacyProfileCharValue

Y

 

 

agreement

N

 

 

 

Further specify any rules on the creation of the entity

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

partyPrivacyProfileCharValue

value must be one of the possibilities described in the referenced profile type

agreedByParty

role and party are mandatory

partyPrivacyProfileType

reference must be set

agreement

reference must be set

 

Example : Creation of a new profile type, which is an instantiation of the privacy profile type ‘103’ already created in the privacy referential.

 

REQUEST

POST privacyManagement/partyPrivacyProfile

Content-type: application/json

 

{

  "name" : "John Doe's Privacy Profile" ,

  "description" : "This is John Does Privacy profile" ,

  "dateCreated" : "2016-03-16T15:15:51.209Z" ,

  "status" : "agreed" ,

  "validFor" : {

    "startDateTime" : "2016-03-16T15:15:51.209Z" ,

    "endDateTime" : ""

  },

  "agreedByParty" : {

    "id" : "2345" ,

    "href" : "http ://serverLocation:port/partyManagement/individual/2345" ,

    "role" : "Customer" ,

    "name" : "John Doe"

  },

  "partyPrivacyProfileType" : {

    "id" : "103" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103"

  },

  "partyPrivacyProfileCharValue" : [

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "10" ,

          "href" : "http ://serverLocation:port/partyManagement/organization/10" ,

          "role" : "Administrator" ,

          "name" : "Orange"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        },

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : "2016-06-16T15:15:51.209Z"

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        }

      ],

      "characteristicAgreement" : {

        "id" : "6810" ,

        "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810"

      }

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "value" : "Unauthorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    }

  ],

  "agreement" : {

    "id" : "6810" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810" ,

    "type" : "commercial"

  }

}

RESPONSE

201

Content-Type: application/json

 

{

  "id" : "394" ,

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfile/394" ,

  "name" : "John Doe's Privacy Profile" ,

  "description" : "This is John Does Privacy profile" ,

  "dateCreated" : "2016-03-16T15:15:51.209Z" ,

  "status" : "agreed" ,

  "validFor" : {

    "startDateTime" : "2016-03-16T15:15:51.209Z" ,

    "endDateTime" : ""

  },

  "agreedByParty" : {

    "id" : "2345" ,

    "href" : "http ://serverLocation:port/partyManagement/individual/2345" ,

    "role" : "Customer" ,

    "name" : "John Doe"

  },

  "partyPrivacyProfileType" : {

    "id" : "103" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyProfileType/103"

  },

  "partyPrivacyProfileCharValue" : [

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "ADMIN" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "10" ,

          "href" : "http ://serverLocation:port/partyManagement/organization/10" ,

          "role" : "Administrator" ,

          "name" : "Orange"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "INFORMATION" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        },

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "MARKETING" ,

      "value" : "Authorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : "2016-06-16T15:15:51.209Z"

      },

      "relatedParty" : [

        {

          "id" : "11" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/11" ,

          "role" : "Vendor" ,

          "name" : "Alice"

        }

      ],

      "characteristicAgreement" : {

        "id" : "6810" ,

        "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810"

      }

    },

    {

      "name" : "eMailAddress" ,

      "privacyUsagePurpose" : "RESEARCH" ,

      "value" : "Unauthorized" ,

      "validFor" : {

        "startDateTime" : "2016-03-16T15:15:51.209Z" ,

        "endDateTime" : ""

      },

      "relatedParty" : [

        {

          "id" : "12" ,

          "href" : "http ://serverLocation:port/partyManagement/individual/12" ,

          "role" : "Employee" ,

          "name" : "Bob"

        }

      ]

    }

  ],

  "agreement" : {

    "id" : "6810" ,

    "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810" ,

    "type" : "commercial"

  }

}

 

 

POST /privacyManagement/partyPrivacyAgreement

This operation is used to create a privacy agreement.

  • The identifier is a string that can consist of numbers, not necessarily alphanumeric
  • The mandatory element(s) is/are:
    • name
    • type
    • engagedPartyRole
    • agreementItem

When using following elements there are some mandatory attributes within each element:

  • Within “engagedPartyRole”
    • id
    • name
  • Within “associatedAgreement”
    • id
    • href
  • The id is generated automatically

Behavior :

  • Return Status Codes:
    • 201 – privacy profile was created successfully
    • 400 - Bad Request Error
    • 500 - The server encountered an unexpected condition which prevented it from fulfilling the request

Specify the attributes required when an entity is created (and their default values if not):

Attribute name

Mandatory

Default

Rule

id

N

Automatically generated

If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used

agreementPeriod

N

 

 

completionDate

N

Current date

 

description

N

 

 

documentNumber

N

 

 

initialDate

N

 

 

name

Y

 

 

statementOfIntent

N

 

 

status

N

 

 

type

Y

 

 

version

N

0

 

agreementSpecification

N

 

 

agreementItem

Y

 

 

engagedPartyRole

Y

 

 

agreementAuthorization

N

 

 

characteristic

N

 

 

associatedAgreement

N

 

 

partyPrivacyProfile

N

 

 

partyPrivacyProfileCharValue

N

 

 

 

Further specify any rules on the creation of the entity

Rule name

Rule/Pre Condition/Side Effects/Post Conditions

engagedPartyRole

id and name are mandatory

associatedAgreement

id and href are mandatory

 

Example : Creation of an Agreement resource, with only the mandatory attributes.

 

 

 

REQUEST

POST privacyManagement/partyPrivacyProfile

Content-type: application/json

 

{

  "name" : "Customer mass market privacy agreement" ,

  "type" : "commercial" ,

  "agreementItem" : [

    {

      "productOffering" : [

        {

          "href" : "https://host:port/productOffering/productOffering/9559" ,
          "id" : "9559" ,
          "name" : "Privacy Service" ,
          "bundledProductOffering" : [
            {
              "href" : "https://host:port/productOffering/bundledProductOffering/7120" ,
              "id" : "7120" ,
              "name" : "Magic Offer" ,
              "bundledProductOffering" : []
            }
          ]

        }

      ],

      "termOrCondition" : [

        {

          "description" : "This agreement term or condition …" ,

          "id" : "8905" ,

          "validFor" : {

            "startDateTime" : "2016-03-16T15:15:51.211Z" ,

            "endDateTime" : "2016-09-16T15:15:51.211Z"            

          }

        }

      ]

    }

  ],

  "engagedPartyRole" : [

    {

      "href" : "http://serverLocation:port/partyManagement/partyRole/1" ,

      "id" : "1" ,

      "name" : "Customer" ,

      "partyId" : "2345" ,

      "partyName" : "John Doe"

    }

  ]

}

RESPONSE

201

Content-Type: application/json

 

{

  "href" : "http://serverlocation:port/privacyManagement/partyPrivacyAgreement/6810" ,

  "id" : "6810" ,

  "completionDate" : "2016-10-16" ,

  "name" : "Customer mass market privacy agreement" ,

  "type" : "commercial" ,

  "version" : "0" ,

  "agreementItem" : [

    {

      "productOffering" : [

        {

          "href" : "https://host:port/productOffering/productOffering/9559" ,
          "id" : "9559" ,
          "name" : "Privacy Service" ,
          "bundledProductOffering" : [
            {
              "href" : "https://host:port/productOffering/bundledProductOffering/7120" ,
              "id" : "7120" ,
              "name" : "Magic Offer" ,
              "bundledProductOffering" : []
            }
          ]

        }

      ],

      "termOrCondition" : [

        {

          "description" : "This agreement term or condition …" ,

          "id" : "8905" ,

          "validFor" : {

            "startDateTime" : "2016-03-16T15:15:51.211Z" ,

            "endDateTime" : "2016-09-16T15:15:51.211Z"            

          }

        }

      ]

    }

  ],

  "engagedPartyRole" : [

    {

      "href" : "http://serverLocation:port/partyManagement/partyRole/1" ,

      "id" : "1" ,

      "name" : "Customer" ,

      "partyId" : "2345" ,

      "partyName" : "John Doe"

    }

  ]

}

 

 

DELETE /privacyManagement/partyPrivacyProfileType/{ID} or /partyPrivacyProfile/{ID} or /partyPrivacyAgreement/{ID}

Only useful and allowed for administration matters

 

REQUEST

DELETE privacyManagement/partyPrivacyProfileType/103

 

 

RESPONSE

200

 

 

 

POST /privacyManagement/importJob

ImportJob Tasks are created as resources.

The ImportJob is attached to the URL of the root resource where the content of the file specified by the ImportJob will be applied.

For example to apply the content of the import file located at ftp://ftp.myPrivacy.com/privacy/54 to the privacyManagement root.

REQUEST

POST  ../privacyManagement/importJob

Content-type: application/json

 

{

"url" : "ftp://ftp.myPrivacy.com/privacy/54"
 

}

RESPONSE

201

Content-Type: application/json

Location: ../privacyManagement/importJob/554

 

 

{
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/importJob/54" ,
        "status" : "running" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,

        "url" : "ftp://ftp.myPrivacy.com/party/54"

            }    

 

POST /privacyManagement/exportJob

ExportJob Tasks are created as resources.

The ExportJob is attached to a specific resource acting as the root for the collection of resources to be streamed to a File.

An ExportJob can be attached to a specific Resource in the Privacy Management application or may be attached to the Party Privacy Profile Type, Profile or Agreement collections

  • ../privacyManagement/exportJob

Export all the resources within privacyManagement subject to query and path assignments.

  • ../privacyManagement/partyPrivacyProfileType/exportJob

Export all the privacy profile type resources within privacyManagement subject to query and path assignments.

 

For example:

REQUEST

POST ../privacyManagement/exportJob

Content-type: application/json

 

{

}

RESPONSE

201

Content-Type: application/json

Location: ../privacyManagement/exportJob/54

 

 

{
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/exportJob/54" ,
        "status" : "running" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacy/54"
    }    

 

GET privacyManagement/exportJob

ExportJob resources can be found under the API/exportJob collection and may be retrieved using the normal GET constru cts.

For example:

REQUEST

GET ../privacyManagement/exportJob/54

Content-type: application/json

 

{

}

RESPONSE

200

Content-Type: application/json

 

{
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/exportJob/54" ,
        "status" : "running" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacy/54"
    }    

 

GET privacyManagement/importJob

ImportJob resources can be found under the API/importJob collection and may be retrieved using the normal GET constructs.

For example:

REQUEST

GET ../privacyManagement/importJob/54

Content-type: application/json

 

{

}

RESPONSE

200

Content-Type: application/json

 

{
        "id" : "54" ,
        "href" : "http:/api/privacyManagement/importJob/54" ,
        "status" : "running" ,
        "path" : "privacyManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.myPrivacy.com/privacy/54"
    }    

 

API NOTIFICATION TEMPLATES

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.

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}

 

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.

REQUEST

DELETE /api/hub/{id}

Accept: application/json

 

RESPONSE

204

 

publish {EventTYPE} POST /listener

Description :

Provides the Event description

Behavior :

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

REQUEST

POST /client/listener

Accept: application/json

 

{

"eventType" : "EventType" ,

"eventTime" : "2014-09-27T05:46:25.0Z" ,

"eventId" : "1562231" ,

"event" :

{

    EVENT BODY
}

}

RESPONSE

201

Content-Type: application/json

 

 

Example see TMF REST Design Guidelines.

 


ACKNOWLEDGMENTS

 

VERSION HISTORY

Version Number

Date

Modified by

Description

Version 1.0.0

15/04/2016

Pierre Gauthier

TM Forum

 

Final version

Version 1.0.1

10/06/2016

Alicja Kawecki

TM Forum

Updated cover; minor formatting/style corrections prior to publishing for Fx16

Version 1.0.2

04/10/2016

Alicja Kawecki

TM Forum

Updated cover and Notice to reflect TM Forum Approved status

 

 

RELEASE HISTORY

Release Number

Date

Release led by:

Description

Release 1.0

15/04/2016

Pierre Gauthier

TM Forum

pgauthier@tmforum.org

Fabien Venries (Orange)

Julie Bertrand (Orange)

First Release of Draft Version of the Document.

 

Contributors to Document

Fabien Venries

Orange

Julie Bertrand

Orange

Pierre Gauthier

TM Forum