Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Hide If
special@authenticated
Note
titleTo access this API specification you wil need to be logged in

To login with your TM Forum account please click on the Login button below

Button Hyperlink
titleLogin
typeprimary
urlhttps://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable

Don't have an account? You can register by clicking here:

Button Hyperlink
titleRegister
typeprimary
urlhttps://www.tmforum.org/user-registration/
targettrue

Show If
special@authenticated

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.

Individual Resource

An Individual represents a physical person.
JSON representation of an Individual

{
"id": "i42",
"href": "http://serverlocation:port/partyManagement/individual/i42",
"gender": "male",
"placeOfBirth": "http://goo.gl/maps/l8F9L",
"countryOfBirth": "Austria",
"nationality": "Canadian",
"maritalStatus": "never married",
"disability": [
{
"disability": "blind"
}
],
"birthDate": "1961-03-05T00:00:00.0Z",
"characteristic": [
{
"name": "hobby",
"value": "hockey"
},
{
"name": "",
"value": ""
}
],
"title": "",
"givenName": "John",
"familyName": "Smith",
"middleName": "",
"fullName": "",
"formattedName": "",
"otherName": [
{
"title": "",
"givenName": "",
"familyName": "",
"middleName": "",
"fullName": "",
"formattedName": "",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
}
],
"location": "http://goo.gl/maps/l8F9L",
"status": "Initialized",
"individualIdentification": [
{
"type": "Passport",
"identificationId": "73736625252",
"issuingAuthority": "",
"issuingDate": "2013-06-19T00:00:00.0Z"
},
{
"type": "SocialSecurityNumber",
"identificationId": "33636363",
"issuingAuthority": "",
"issuingDate": "2013-06-19T00:00:00.0Z"
}
],
"externalReference": [
{
"href": "http://facebook.com/17263635",
"type": "FacebookID"
},
{
"href": "http://google.com/17263635",
"type": "GoogleID"
}
],
"relatedParty": [
{
"id": "1",
"href": "http://serverlocation:port/partyManagement/organization/1",
"role": "Employee",
"name": "Richard Cole",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
}
],
"contactMedium": [
{
"type": "Email",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"emailAddress": "

...

[email protected]tmforum.com"
}
},
{
"type": "PostalAddress",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"city": "Wien",
"country": "Austria",
"postcode": "1020",
"stateOrProvince": "Quebec",
"street1": "Lassallestrasse7",
"street2": ""
}
},
{
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"type": "mobile",
"number": "+436641234567"
}
},
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"type": "business",
"number": "+436641234567"
}
}
]
}


Field Descriptions :
Characteristic: describes the characteristics of the individual such as individual hobbies, center of interests.

Field

Description

name

Name of the characteristic

value

Value of the characteristic


ContactMedium: indicates the contact medium that could be used to contact the customer.

Field

Description

preferred

If true, indicates that is the preferred contact medium

type

Email address, telephone number, postal address

validFor

The time period that the contact medium is valid for


Disability: indicate lack or inadequate strength or ability

Field

Description

disability

Physical or mental handicap


ExternalReference: to manage touch points to external OTT identifiers for the person (facebook, google+, …).

Field

Description

href

External reference

type

Reference type



Individual: represents a physical person.

Field

Description

birthdate

Birth date

countryOfBirth

The country of birth

deathDate

Death date

familyName

Last name

formattedName

A formatted name useful for specific contexts (Chinese, Japanese, Korean, …)

fullName

Full name flatten (first, middle, and last names)

gender

Gender

givenName

First name

href

Reference of the individual

id

Unique identifier for the individual

location

Temporary current location of the individual (may be used if the individual has approved its sharing)

maritalStatus

Marital status (married, divorced, widow, …)

middleName

Middle names

nationality

Nationality

placeOfBirth

An hyperlink to the place of birth

status

Status of the individual - Initialized, Validated, Deceased

title

Useful for titles (aristocratic, social, …) : Pr, Dr, Sir, …


IndividualIdentification: represents our registration of information used as proof of identity by an individual (passport, national identity card, driver's license, social security number, birth certificate)

Field

Description

identificationId

identifier

issuingAuthority

Authority which has issued the identifier (social security, town hall…)

issuingDate

Date at which the identifier was issued

type

Identification type (passport, national identity card, driver's license, social security number, birth certificate)


Medium: describes the contact medium that could be used to contact the customer

Field

Description

city

City

country

Country

emailAddress

Full email address in standard format

type

Type of medium (fax, mobile phone…)

number

Phone number

postcode

Postcode

stateOrProvice

State or province

street1

Describes the street

street2

Complementary street description


OtherName: To keep track of other names (for example the old name of a woman before marriage or an artist name)

Field

Description

title

Useful for titles (aristocratic, social, …): Pr, Dr, Sir,…

givenName

First name

familyName

Last name

middleName

Middle names

fullName

Full name flatten (first, middle, and last names)

formattedName

A formatted name useful for specific contexts (Chinese, Japanese, Korean, …)

validFor

The period for which the other name is valid


RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Reference of the relatedParty, could be a party reference or a partyRole reference

role

Role of the related party

name

Name of the related party

validFor

The period for which the related party is valid



UML Model:
Image Modified

Organization Resource

JSON representation of an Organization

{
"id": "128",
"href": "http://serverlocation:port/partyManagement/organization/128",
"isLegalEntity": true,
"type": "Company",
"existsDuring": {
"startDate": "2013-04-19T16:42:23.0Z"
},
"tradingName": "Telekom",
"nameType": "Co.",
"status": "Initialized",
"otherName": {
"nameType": "Co.",
"tradingName": "Orange",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
"characteristic": {
"name": "industry",
"value": "telecom"
},
"organizationIdentification": {
"type": "CompanyRegistrationNumber",
"identificationId": "374748328",
"issuingAuthority": "",
"issuingDate": "2013-06-19T00:00:00.0Z",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
"externalReference": [
{
"href": "http://facebook.com/17263635",
"type": "FacebookID"
},
{
"href": "http://google.com/17263635",
"type": "GoogleID"
}
],
"relatedParty": {
"id": "12",
"href": "http://serverlocation:port/partyManagement/organization/12",
"role": "Vendor",
"name": "Richard Cole",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
"organizationParentRelationship": {
"relationshipType": "Juridical",
"id": "13",
"href": "http://serverlocation:port/partyManagement/organization/13",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
"organizationChildRelationship": {
"relationshipType": "Juridical",
"id": "16",
"href": "http://serverlocation:port/partyManagement/organization/16",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
}
},
"contactMedium": [
{
"type": "Email",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"emailAddress": "

...

[email protected]tmforum.com"
}
},
{
"type": "PostalAddress",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"city": "Wien",
"country": "Austria",
"postcode": "1020",
"stateOrProvince": "Quebec",
"street1": "Lassallestrasse7",
"street2": ""
}
},
{
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"type": "mobile",
"number": "+436641234567"
}
},
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"medium": {
"type": "business",
"number": "+436641234567"
}
}
]
}


Field Descriptions :
Characteristic: describes the characteristics of the individual such as individual hobbies, center of interests.

Field

Description

name

Name of the characteristic

value

Value of the characteristic


ContactMedium: indicates the contact medium that could be used to contact the customer.

Field

Description

preferred

If true, indicates that is the preferred contact medium

type

Email address, telephone number, postal address

validFor

The time period that the contact medium is valid for


ExternalReference: to manage touch points to external OTT identifiers for the organization (facebook, google+, …).

Field

Description

href

External reference

type

Reference type


Medium: describes the contact medium that could be used to contact the customer

Field

Description

city

City

country

Country

emailAddress

Full email address in standard format

type

Type of medium (fax, mobile phone…)

number

Phone number

postcode

Postcode

stateOrProvice

State or province

street1

Describes the street

street2

Complementary street description



Organization: represents a group of people identified by shared interests or purpose. Because of the complex nature of many businesses, both organizations and organization units are represented by the same business entity in this model..

Field

Description

existsDuring

Details the establishment of the organization and its cessation

href

Reference of the organization

id

Unique identifier for the organization

isLegalEntity

To tag if the organization is a legal entity known by national referential

nameType

"Co.", "Inc.", "Ltd.", "Pty Ltd." , "Plc.", "Gmbh"

status

Status of the organization - Initialized, Validated, Closed

tradingName

The name that the organization (unit) trades under

type

Type of Organization (Company, …)


OrganizationIdentification: represents our registration of information used as proof of identity by an organization

Field

Description

identificationId

identifier

identificationId

The name that the organization trades under

issuingAuthority

Authority which has issued the identifier (chamber of commerce…)

issuingDate

Date at which the identifier was issued

type

Type of identification information used to identify the company in a country or internationally

validFor

The period for which the identification information is valid


OrganizationChildRelationship: represents the links between organizations: useful to describe an organization structure between headquarters, affiliates,…It indicates the children of the organization.

Field

Description

id

Unique identifier of the child organization

href

Reference of the child organization

relationshipType

Juridical, hierarchical, geographical, functional…

validFor

The time period the relationship is valid



OrganizationParentRelationship: represents the links between organizations: useful to describe an organization structure between headquarters, affiliates,…It indicates the parent of the organization.

Field

Description

id

Unique identifier of the parent organization

href

Reference of the parent organization

relationshipType

Juridical, hierarchical, geographical, functional…

validFor

The time period the relationship is valid


OtherName: To keep track of other names (for example the old name of a woman before marriage or an artist name)

Field

Description

nameType

Co., Inc., Ltd., Pty Ltd. , Plc., Gmbh

tradingName

The name that the organization trades under

validFor

The period for which the other name is valid


RelatedParty: Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Reference of the relatedParty, could be a party reference or a partyRole reference

role

Role of the related party

name

Name of the related party

validFor

The period for which the related party is valid




UML Model:
Image Modified

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
../partyManagement/individual

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/catalogManagement/exportJob/54",
        "status": "running",
        "path": "partyManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myParty.com/party/54"
    }   


UML Model:
Image Modified

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
../partyManagement/individual

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/ partyManagement/importJob/54",
        "status": "completed",
        "path": "partyManagement/",
        "content-type": "application/json",
        "errorLog": "",
        "creationDate": "2013-04-19T16:42:23-04:00",
        "completionDate": "2013-04-21T16:42:23-04:00",
        "url": "ftp://ftp.myParty.com/party/54"
    }   


UML Model:
Image Modified

Notification Resource Models

8 notification event types are defined :

  1. IndividualCreateNotification
  2. IndividualUpdateNotification
  3. IndividualDeleteNotification
  4. OrganizationCreateNotification
  5. OrganizationUpdateNotification
  6. OrganizationDeleteNotification
  7. ImportJobCompletionNotification
  8. ExportJobCompletionNotification

UML Model:
Image Modified
Event: IndividualCreateNotification

{
"eventType": "IndividualCreateNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "1154231",
"event": {
"individual":
{
"id": "12",
Following a whole representation of the Individual with all its attributes See Individual Resource.
}
}
}


Event: IndividualUpdateNotification

{
"eventType": "IndividualUpdateNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "119331",
"event": {
"individual":
{
"id": "12",
Following a whole representation of the Individual with all its attributes See Individual Resource.
}
}
}


Event: individualDeleteNotification

{
"eventType": "IndividualDeleteNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "1189231",
"event": {
"individual":
{
"id": "12",
Following a whole representation of the Individual with all its attributes See Individual Resource.
}
}
}


ORGANIZATION Notifications

  1. Create
  2. Update
  3. Delete

UML Model:
Image Modified
Event: OrganizationCreateNotification

{
"eventType": "OrganizationCreateNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "1154391",
"event": {
"organization":
{
"id": "128",
Following a whole representation of the Organization with all its attributes See Organization Resource.
}
}
}


Event: OrganizationUpdateNotification

{
"eventType": "OrganizationUpdateNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "1156731",
"event": {
"organization":
{
"id": "128",
Following a whole representation of the Organization with all its attributes See Organization Resource.
}
}
}


Event: OrganizationDeleteNotification

{
"eventType": "OrganizationDeleteNotification",
"eventTime": "2014-09-27T05:46:25.0Z",
"eventId": "1154278",
"event": {
"organization":
{
"id": "128",
Following a whole representation of the Organization with all its attributes See Organization Resource.
}
}
}



Export and Import Job Notifications

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

UML Model:
Image Modified

Event: ExportJobCompletionNotification

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




Event: ImportJobCompletionNotification

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

 


© TM Forum 2015. All Rights Reserved