42 People Connections Service REST APIs

Oracle WebCenter Portal provides REST APIs to support the People Connections service. You can use the People Connections service REST APIs to perform the following actions:

View a stream of your connections' activities in an activity stream
Browse a profile or connections list
Update profile status messages
Create and delete connection lists
Add and remove members from connection lists
Create, read, and delete messages
Read and delete feedback

This chapter describes the REST APIs associated with the People Connections service. It includes the following sections:

Section 42.1, "Activity Stream REST APIs"
Section 42.2, "Connections and Profile REST APIs"
Section 42.3, "Feedback REST APIs"
Section 42.4, "Message Board REST APIs"
Section 42.5, "Creating an Invitation"

See Also:

For an introduction to the REST APIs, see Chapter 54, "Using Oracle WebCenter Portal REST APIs."

42.1 Activity Stream REST APIs

Use the Activity Stream REST APIs to browse user application activities in an activity stream. This section provides information about the REST APIs to use to perform this action. It includes the following subsections:

Section 42.1.1, "Activity Stream Entry Point"
Section 42.1.2, "Activity Stream Resource Type Taxonomy"
Section 42.1.3, "Activity Stream Security Considerations"
Section 42.1.4, "Activity Stream Resource Types"

Note:

Because REST APIs can be configured in many different ways, it's possible that not all of a user's activities will be returned, allowing the REST client to customize how the Activity Stream behaves separately from the Webcenter Portal application.

42.1.1 Activity Stream Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the People Connections service, each feature has its own link element. For example, to find the entry point for the Activity Stream feature of the People Connections service, find the link elements with a resourceType of:

urn:oracle:webcenter:activities:stream

The corresponding href or template element provides the URI entry point, which retrieves application activities for the current user from the Activity Stream. The client sends HTTP requests to this entry point to work with the Activity Stream feature of the People Connections service.

See Also:

For more information about the Resource Index, see Section 54.5.1, "The Resource Index."

For more information about resource types, see Section 54.5.2.1, "Resource Type."

42.1.2 Activity Stream Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Section 42.1.4, "Activity Stream Resource Types."

The resource type taxonomy for the Activity Stream feature of the People Connections service is:

urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:activity

42.1.3 Activity Stream Security Considerations

You must be logged in to the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Section 54.8, "Security Considerations for WebCenter Portal REST APIs."

42.1.4 Activity Stream Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

"urn:oracle:webcenter:activities:stream"
"urn:oracle:webcenter:activities:activity"

urn:oracle:webcenter:activities:stream

The stream response contains URIs for use in retrieving activities from the Activity Stream.

You can retrieve the activities from a user's stream or activities from a user's connections' streams. To have even greater control over which activities to retrieve, use the activity stream query filter. With the query filter, you can:

Specify the user to query
Include the user's connections' activities in the results
Include activities from spaces, including the Home space, in the results
Restrict the results to activities from specific services

The options available to you depend on the path you take to get to the stream resource and the rel of the link that you use. For example, the activity stream query filter is available only from links with a rel attribute of urn:oracle:webcenter:activities:stream. If you access the activity stream query filter from the person resource, the personGuid parameter is prefilled.

Table 42-1 shows the activities returned depending on the rel element of the link.

Table 42-1 Activities Returned by stream

rel	Returns
`urn:oracle:webcenter:activities:stream:person`	Activities from the user's stream (`GUID/@self`)^Foot 1
`urn:oracle:webcenter:activities:stream:connections`	Activities from the user's connections' streams (`GUID/@connections`)^Footref 1
`urn:oracle:webcenter:activities:stream`	Activities determined by the activity stream query filter
`urn:oracle:webcenter:activities:stream:space`	Activities from the space activity stream
`urn:oracle:webcenter:activities:stream:list`	Activities from the space activity list

^Footnote 1GUID can be any valid user GUID or @me.

Navigation Paths to stream

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   stream (rel="urn:oracle:webcenter:activities:stream:person" or
               "urn:oracle:webcenter:activities:stream")

resourceIndex
   person
      stream (rel="urn:oracle:webcenter:activities:stream:person" or
                  "urn:oracle:webcenter:activities:stream:connections" or
                  "urn:oracle:webcenter:activities:stream")

resourceIndex
   person
      list
         stream

resourceIndex
   space
      stream

stream
   activity
      param
         stream (rel="urn:oracle:webcenter:activities:stream:space")

personReference
   stream

Supported Methods for stream

The following method is supported by the stream resource:

GET
- request—Parameters:
  - startIndex, itemsPerPage
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see "Common Request Query Parameters".
  
  The following additional parameters are available for the query filter URI:
  - data – Returns specified data only (for more information, see "Common Request Query Parameters"). For the stream resource, if you specify the constant 'data' as the data parameter, all of the basic information about the resource is returned except "comments" and "likes" summaries. If you want to return comments or likes, specify the data parameter value 'commentsSummary' or 'likesSummary'.
    
    Note:
    
    You can specify multiple data values as a comma separated list. For example, data=data, commentsSummary.
  - personGuid—(Required) Retrieves activities from the stream for the specified user. Valid values: any valid user GUID or @me.
  - serviceIds—Retrieves activities only for the specified services. Valid values: An asterisk (*) returns all services. If null or empty, uses the user preference settings for service filters (from the settings link in the top bar).
  - personal—Includes the specified user's activities in the Home space. Valid values: true or false. Default value: false.
  - connections—Includes activities from the streams of the specified user's connections. Valid values: true or false. Default value: false.
  - groupSpaces—Includes activities from all spaces of which the specified user is a member. Valid values: true or false. Default value: false.
  - connectionListIds – A comma separated list of connection list names that specifies the connection lists used to show activities.
  - groupSpaceGuids – A comma separated list of space GUIDs used to show activities.
  - userGroupSpaceActivities – Specifies whether or not to show the user's activities in their spaces. Valid values: true or false. Default value: false.
  - followedObjects – Specifies whether or not to show all activities for followed objects that both the current user and the specified user follow. Valid values: true or false. Default value: false.
  - followedObjectsUserActivities – Specifies whether or not to show the specified user's activities for followed objects that both the current user and the specified user follow. Valid values: true or false. Default value: false.
  - advancedQuery – Specifies filters against streamed activities. Create filters for user names, service IDs, and object details, such as a document's display name.
    
    Note:
    
    You must plug actual values into the advancedQuery parameter. You cannot pass EL expressions directly into the parameter. Typically, the REST API client handles an EL transformation manually and inserts the actual object data value into the REST URL. See the example below, and see also Section 40.3, "What You Should Know About the Activity Stream Advanced Query Option."
  For example, the following URI returns activities from the current user's activity stream, for all services that the user has configured in their personal preference settings for service filters. It returns activities from the user's personal space and from the streams of the user's connections:
```
http://host:port/rest/api/activites?personal=true&connections=true&personGuid=@me&token=token
```
  The following URI returns only the user's personal profile and connections activities:
```
http://host:port/rest/api/activities?serviceIds=oracle.webcenter.peopleconn
ections.profile,oracle.webcenter.peopleconnections.connections&personal=
true&personGuid=@me&token=token
```
  This next example illustrates how to use the advancedQuery parameter. As explained previously, you cannot pass an EL expression to advancedQuery. The REST API client must first obtain the actual data object value, and that value can then be passed to advancedQuery. For example, to filter activities for a particular space, you can pass the GUID of the space's scope to advancedQuery:
```
http://host:port/rest/api/activities?personGuid=@me&advancedQuery=AE.SCOPE_ID%20%3D%20\%27s8bba98ff_4cbb_40b8_beee_296c916a23ed\%27&ttoken=token
```
  where s8bba98ff_4cbb_40b8_beee_296c916a23ed is the GUID of the space. Note that the query string must be encoded with the appropriate escape codes. For a list of EL expressions that can be used to obtain values for advancedQuery, see Section 40.3, "What You Should Know About the Activity Stream Advanced Query Option."
- response—Body: 0 or more activities
  
  Note:
  
  Because the stream resource includes activity items, the response may also return resource links for the objects referenced in the activity.

Resource Types Linked to From stream

Table 42-2 lists the resource types that the client can link to from the stream resource.

Table 42-2 Related Resource Types for stream

rel	resourceType
self urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
	urn:oracle:webcenter:activities:activity

urn:oracle:webcenter:activities:activity

The activity response contains the data for activities and URIs for use in retrieving all the data you need from an activity that is included in an Activity Stream.

Navigation Paths to activity

This section shows how the client can navigate through the hypermedia to access the activity resource:

resourceIndex
   stream
      activity

resourceIndex
   person
      stream
         activity

resourceIndex
   space
      stream
         activity

Supported Methods for activity

No methods are supported for activity. Activities are currently available only from the stream resource type.

Resource Types Linked to from activity

Table 42-3 lists the resource types that the client can link to from this resource.

Table 42-3 Related Resource Types for urn:oracle:webcenter:activities:activity

rel	resourceType
self	`urn:oracle:webcenter:activities:activity`
icon	`urn:oracle:webcenter:activities:activity:icon`

Read-only Elements for activity

Table 42-4 lists the read-only elements for the activity resource.

See Also:

For information about projection, see "Common Request Query Parameters".

Note:

The activity will also return a link to an activity icon in the links section of the response, if an icon is available. See urn:oracle:webcenter:activities:activity:icon.

Table 42-4 Read-Only Elements for activity

Element	Type	Description
`activityType`	String	Activity type Unique within the service. For example the Discussions service can return the `activityType` `createForum`.
`commentsCount`	String	If you specify `commentsSummary` in the data parameter, then the `commentsCount` parameter will be returned.
`createdDate`	Date (String)^Foot 1	Date the activity was created.
`description`	String	The description of the activity.
`detail`	String	Detail information for the activity, if available. For example, this might return the contents of a message, the file name of a document, and the like. Similar to `detailURL`. Both, either, or neither can be used.
`detailURL`	String	Detail information for the activity, if available. Similar to `detail`. Both, either, or neither can be used.
`displayDescription`	String	A pre-formatted, internationalized description.
`displayMessage`	String	A pre-formatted, internationalized message (does not include template information).
`groupSpace`	groupSpaceReference	Information about the space in which the activity was performed Note: This reference is not present for activities that did not happen in a space (for example, activities that happened in the Home space). Also, because creation of a space happens in a personal space, that activity does not have this element either.
`id`	String	Unique ID of the message
`isSummary`	true or false	Indicates whether or not this activity is a summary of other activities.
`likesCount`	String	If you specify `likesSummary` in the data parameter, then the `likesCount` parameter will be returned.
`message`	String	Localized string for this activity This may contain replacement strings within curly braces ({}).
`permission`	PRIVATE SHARED PUBLIC	Permission level of this activity
`scope`	String	Scope of the activity This might return a space, like the Home space. For example, for a space, it returns a string similar to the following: s8bba98ff_4cbb_40b8_beee_296c916a23ed
`serviceId`	String	Unique ID of the service that created the activity Note: For a list of WebCenter Portal service IDs, see Table G-7, "Service IDs".
`templateParams`	urn:oracle:webcenter:activities:parameter	A list of `param` elements that capture data related to an activity. A key provided with each `templateParam` <param> element allows you to plug one or more data items into a parameterized activity message. See "Understanding the templateParams Element".
`custom`	Param	The custom parameter includes a `displayName`, `key`, and `type`, and may or may not have a URL.

^Footnote 1Data types, such as DATE and BOOLEAN, are stored in the API as STRING. The DATE data type returns a Java standard date format, for example, 2009-08-21T14:43:11.0013-0700, with 0700 representing the time zone.

Understanding the templateParams Element

Suppose you want to display the most recent messages for a user named Carl. You want to display information like this: "Carl created the space Customer Feedback". The templateParams elements helps you solve this problem.

The templateParams element is returned in objects of type oracle:webcenter:activities:activity. This element captures a lot of data related to an activity. For example, if a user creates a new space, the templateParams element for that activity captures information about the user and about the space. Keys are provided that allow you to perform string substitutions in a parameterized message string related to the activity.

For example, if the user creates a space, the returned activity object contains a <message> item that is parameterized like this:

<message>{actor[0]} has created the space {object[0]}</message>

By parsing the templateParams element for the activity, you can find the available keys that allow you to perform string substitutions as well as appropriate data to display, like the name of the user and the activity.

For a detailed example showing how you might code a UI using templateParams to display information about an activity, see Section 54.13.2, "Displaying Activity Stream Data."

The templateParams element also provides links to comments, likes, commentsSummary, and likesSummary objects, if they are requested using the data parameter. These links let you query for all the comments or likes for an object or post a new comment or like. The summary links returns the comments or likes count and several recent comments or likes. See also "Understanding Comments and Likes".

The links returned with the templateParams element vary depending on what kind of object is returned, like a user, document, space (GS), or custom object. For more information, see "urn:oracle:webcenter:activities:parameter".

Note:

The templateParams element can sometimes contain elements that are not directly referenced in the message.

If a rel link is marked "via," this means it is a link to the underlying REST object–for instance, the document not the parameter. If a rel link is marked "alternate" and type "text/html," it is a link to the HTML page for that object. Space (GS) objects include an activity stream link for spaces. Users have icon and activity stream links. Other objects can have an alt link to the tagged item, as well as the related tagged items list, if tagging is enabled for that object. If a regular object supports comments or likes, it can include the comments/commentsSummary and likes/likesSummary, as explained previously.

Understanding Comments and Likes

Likes and Comments only show up if they are requested using the data parameter. They do not appear by default. Comments are associated with the object referenced by the activity, not the activity itself. For example, if you edit a document, then the comments will be associated with the document, not the edit activity. This means that if you "like" the document, then the comments from editing it will also show up.

The links associated with comments and likes are:

comments – The comments link lets you query for all the comments for an object. This link also lets you POST a new comment. For a comments POST, the text field is required.
commentsSummary – The commentsSummary link returns the comments count and several recent comments.
likes – The likes link lets you query for all the likes for an object. This link also lets you POST a new like. There are no required fields for a likes POST.
likesSummary – The likesSummary link returns the likes count and the current user's like (if available).

Note:

Like objects themselves only support DELETE, not GET. The likesCount and commentsCount items return the number of likes or comments for the current object.

urn:oracle:webcenter:activities:parameter

The templateParams element returns a set of param elements. The param elements return data specific to the type of activity object returned. The possible types of param elements include:

user – Returns the displayName, guid, id, key, primaryId, and type.
document – Returns the displayName, iconUrl, id, key, primaryId, and type.
custom – Returns displayName, key, and type, and may or may not have a URL.

A param can also be a variable reference or key of the general form {prefix[index].variable}.

urn:oracle:webcenter:activities:activity:icon

Use this resource type to get the icon of the activity, if available (GET).

Navigation Paths to activities:activity:icon

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   activities
      activity
         icon

Supported Methods for icon

The following methods are supported by this resource:

GET – Returns the icon used for the named activity.

Resource Types Linked to from icon

Table 42-5 lists the resource types that the client can link to from this resource.

Table 42-5 Related Resource Types for urn:oracle:webcenter:activities:activity:icon

rel	resourceType
self	`urn:oracle:webcenter:activities:activity:icon`
urn:oracle:webcenter:parent	`urn:oracle:webcenter:activities:activity`

42.2 Connections and Profile REST APIs

Use the Connections and Profile REST APIs to browse a profile or a connections list, manage connections lists, add or remove connections, send invitations to connect, and update a profile status message.

This section provides information about the REST APIs to use to perform these actions. It includes the following subsections:

Section 42.2.1, "Connections and Profile Entry Point"
Section 42.2.2, "Connections and Profile Resource Type Taxonomy"
Section 42.2.3, "Connections and Profile Security Considerations"
Section 42.2.4, "Connections and Profile Resource Types"

42.2.1 Connections and Profile Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the People Connections service, each feature has its own link element. For example, to find the entry points for Connections and Profile features of the People Connections service, find the link elements with a resourceType of:

urn:oracle:webcenter:people (returns the current user profile)

urn:oracle:webcenter:people:person (enables you to query for a user)

urn:oracle:webcenter:people:invitations (returns invitations sent or received by the current user)

Note:

The people:person and people:invitations resource types have a template but not an href.

The corresponding href or template element provides the URI entry point, which returns a list of people (people) or an individual user (people:person). The client sends HTTP requests to this entry point to work with the Connections and Profile features of the People Connections service.

See Also:

For more information about the Resource Index, see Section 54.5.1, "The Resource Index."

For more information about resource types, see Section 54.5.2.1, "Resource Type."

42.2.2 Connections and Profile Resource Type Taxonomy

The resource type taxonomy for the Connections and Profile features in the People Connections service is:

urn:oracle:webcenter:people
   urn:oracle:webcenter:people:person
   urn:oracle:webcenter:people:icon
   urn:oracle:webcenter:people:person:list
      urn:oracle:webcenter:people:person:listNames
      urn:oracle:webcenter:people:person:listName
      urn:oracle:webcenter:people:person:list:member
      urn:oracle:webcenter:people:person:status
   urn:oracle:webcenter:people:invitations
      urn:oracle:webcenter:people:invitation

42.2.3 Connections and Profile Security Considerations

You must be logged in to the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Section 54.8, "Security Considerations for WebCenter Portal REST APIs."

42.2.4 Connections and Profile Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

"urn:oracle:webcenter:people"
"urn:oracle:webcenter:people:person"
"urn:oracle:webcenter:people:person:list"
"urn:oracle:webcenter:people:person:listNames"
"urn:oracle:webcenter:people:person:listName"
"urn:oracle:webcenter:people:person:list:member"
"urn:oracle:webcenter:people:person:status"
"urn:oracle:webcenter:people:invitations"
"urn:oracle:webcenter:people:invitation"

urn:oracle:webcenter:people

The people response contains URIs for use in retrieving the profile of one or more users.

Navigation Paths to people

This section shows how the client can navigate through the hypermedia to access the people resource:

resourceIndex
   people

Supported Methods for people

The following method is supported by the people resource:

GET
- request—Parameters:
  - startIndex – See "Common Request Query Parameters."
  - itemsPerPage – See "Common Request Query Parameters."
  - projection – See "Common Request Query Parameters."
  - data – The data parameter is a comma separated list that controls which data will be returned in the response. The predefined set basic is equivalent to data=guid,id,displayName. The predefined set data is a standard set that returns all the data for the user, but does not include status, manager, reportees, or photos. The full list of possible values includes the predefined sets basic and data, as well as the following individual data values: guid, id, displayName, birthday, language, timeZone, name, addresses, organizations, workEmail, phoneNumbers, manager, reportees, photos, and status.
    
    If you specify the constant 'data' as the data parameter, all the basic information will be returned for the resource. If both the projection and data query string parameters are present, the data parameter will be used to determine which data to return.
    
    The data parameter can also take any of the following values comma-separated values to return the corresponding data: guid, id, displayName, birthday, language, timeZone, name, addresses, organizations, workEmail, phoneNumbers, manager, reportees, photos, and/or status.
    
    Note:
    
    The data parameter can accept a predefined set, a collection of values, or a mix of sets and values. For example, to get the basic data plus the user's birthday, you can specify data=basic,birthday.
  - links – The links parameter is a comma-separated list that controls which links will be returned in the response. This parameter can accept predefined sets, individual data values, or a combination of predefined sets and individual data values. The predefined sets are basic, data, activitiesSet, connectionsSet, and feedbackSet. These predefined sets are described in "Predefined Sets for the links Parameter".
    
    The individual values for the links parameter are: person, profile, icon, status, messageBoard, activities, personActivities, connectionActivities, connections, listNames, invitation, givenFeedback, receivedFeedback, userGivenFeedback, manager, reportees, member.
    
    If both the projection and links query string parameters are present, the links parameter will be used to determine which links to return.
- response—Body: One or more person objects.

Predefined Sets for the links Parameter

The following items are predefined sets that can be returned in the links parameter. For example, if you specify links=basic, it is the equivalent of specifying data=person,profile,icon. You can also specify additional parameters as needed. For example, you could specify data=basic,birthday.

Note:

Links that are not currently available will not be returned even if they are specified in the links parameter.

basic – A standard set that returns the basic information for the profile and includes person, profile, and icon.
data – A standard set that returns all the basic links for the response plus the connections list, status, and activity stream template.
activitiesSet – Includes activities, personActivities, and connectionActivities.
connectionsSet – Includes connections, listNames, and invitation.
feedbackSet – Includes givenFeedback, receivedFeedback, and userGivenFeedback.

Resource Types Linked to from people

Table 42-6 lists the resource types that the client can link to from the people resource.

Table 42-6 Related Resource Types for people

rel	resourceType
urn:oracle:webcenter:people:icon	urn:oracle:webcenter:people:person
urn:oracle:webcenter:people:person:list:connections	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream:connections	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback
urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
self	urn:oracle:webcenter:people:person:status
urn:oracle:webcenter:people:person:list:list	urn:oracle:webcenter:people:person:list
self	urn:oracle:webcenter:people:person:listName
urn:oracle:webcenter:activities:stream:list	urn:oracle:webcenter:activities:stream

urn:oracle:webcenter:people:icon

Use this resource type to get the icon used for the named profile (GET).

Navigation Paths to people:icon

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   people
      icon

Supported Methods for icon

The following methods are supported by this resource:

GET – Returns the icon used for the named profile.

Note:

This resource includes a template that lets you choose the size of the profile icon to use. The size template parameter can be set to small, medium, or large.

Resource Types Linked to from icon

Table 42-7 lists the resource types that the client can link to from this resource.

Table 42-7 Related Resource Types for urn:oracle:webcenter:people:icon

rel	resourceType
self	`urn:oracle:webcenter:people:icon`
urn:oracle:webcenter:parent	`urn:oracle:webcenter:people`

urn:oracle:webcenter:people:person

The person response contains profile data and the URIs for use in retrieving a user profile.

Navigation Paths to person

This section shows how the client can navigate through the hypermedia to access the person resource:

resourceIndex
   people

resourceIndex
   people
      person

resourceIndex
   person

author
   person

resourceIndex
   activities:stream
      person

Supported Methods for person

The following method is supported by the person resource:

GET
- request—Parameters: q
  
  To retrieve a specified person, the format of q is:
```
q=[loginid:equals:username]
Or
q=[guid:equals:guid]
Or
q=[email:equals:email]
```
  Note:
  
  The parameter q is only on the resourceIndex template for person.
- response—Body: message
  
  See Also:
  
  For information about the response message, see "Read-only Elements for person".

Read-only Elements for person

Table 42-8 lists the read-only elements for the person resource.

Note:

The elements present in a person response depend on how the user repository is configured and the elements it supports. Additionally, several of the pieces of data represented in Table 42-8, such as address, emails, photos, phoneNumbers, and organization, can have multiple instances.

See Also:

Some of the elements listed in Table 42-8 can be returned in predefined sets described in "Predefined Sets for the links Parameter".

Table 42-8 Read-Only Elements for person

Element	Type	Description
`guid`	String	Unique GUID of the person
`id`	String	Unique login ID of the person (that is, the user name, for example, pat_coi)
`displayName`	String	Display name of the person (the user's name, for example, Pat Coi). This may have the same value as `id`, depending on the repository configuration.
`birthday`	Date (String)^Foot 1	Birth date of the person
`connected`	Boolean (String)1	Whether or not this person is connected to the current user
`language`	String	Preferred language of the person
`timeZone`	String	Time zone of the person
`name`	`name`	Name information for the person `name` is a portable contact type. For more information, see Section 54.10.2.1, "name Portable Contact Type."
`address`	`address`	Address information for the person address is a portable contact type. For more information, see Section 54.10.2.2, "address Portable Contact Type."
`emails`	`value`	Emails for the person `emails` is derived from the `value` portable contact type. For more information, see Section 54.10.2.4, "value Portable Contact Type."
`photos`	`value`	Profile photos for the person `photos` is derived from the `value` portable contact type. For more information, see Section 54.10.2.4, "value Portable Contact Type."
`phoneNumbers`	`value`	Phone numbers for the person `phoneNumber` is derived from the `value` portable contact type. For more information, see Section 54.10.2.4, "value Portable Contact Type."
`organizations`	`organization`	Organization information for the person organization is a portable contact type. For more information, see Section 54.10.2.3, "organization Portable Contact Type."
`manager`	personReference	Manager of this person
`reportees`	personReference	Direct reports of this person
`status`	urn:oracle:webcenter:people:person:status	Person's profile status message

^Footnote 1Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

Resource Types Linked to from person

Table 42-9 lists the resource types that the client can link to from the person resource.

Table 42-9 Related Resource Types for person

rel	resourceType
self	urn:oracle:webcenter:people:person
alternate	urn:oracle:webcenter:spaces:profile (HTML)
urn:oracle:webcenter:people:person:list:connections	urn:oracle:webcenter:people:person:list
	urn:oracle:webcenter:people:person:listNames
	urn:oracle:webcenter:people:person:status
urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream:connections	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream
	urn:oracle:webcenter:messageBoard
urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback

urn:oracle:webcenter:people:person:list

The list response contains URIs for use in retrieving all the profiles on a connections list (GET), inviting a user to be a connection or adding a connection to a connections list (POST), and removing a connections list (DELETE).

Navigation Paths to list

This section shows how the client can navigate through the hypermedia to access the list resource:

resourceIndex
   person
      listNames
         list

resourceIndex
   person
      list (rel="urn:oracle:webcenter:people:person:list:connections")

Supported Methods for list

The following methods are supported by the list resource:

GET
- request—Parameters: startIndex, itemsPerPage, projection
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see "Common Request Query Parameters".
- response—Body: 0 or more person items
POST
- request—Body: member
- response—Body: member
See Also:

For information about member in the request and response elements, see "urn:oracle:webcenter:people:person:list:member".
DELETE
- request

Resource Types Linked to from list

Table 42-10 lists the resource types that the client can link to from the list resource.

Table 42-10 Related Resource Types for list

rel	resourceType
self urn:oracle:webcenter:people:person:list^Foot 1	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream

^Footnote 1self rel currently includes "urn:oracle:webcenter:people:person:list:list" instead of the correct "urn:oracle:webcenter:people:person:list". For the @connections default list, it currently includes "urn:oracle:webcenter:people:person:list:connections".

urn:oracle:webcenter:people:person:listNames

The listNames response contains the names of existing connections lists as well as the URIs for use in retrieving the lists (GET) and creating connections lists (POST).

Navigation Paths to listNames

This section shows how the client can navigate through the hypermedia to access the listNames resource:

resourceIndex
   person
      listNames

Supported Methods for listNames

The following methods are supported by the listNames resource:

GET
- request
- response: Body: 0 or more listName items
POST
- request—Body: listName
- response—Body: listName

See Also:

For information about listName, see "urn:oracle:webcenter:people:person:listName".

Resource Types Linked to from listNames

Table 42-11 lists the resource types that the client can link to from the listNames resource.

Table 42-11 Related Resource Types for listNames

rel	resourceType
self	urn:oracle:webcenter:people:person:listNames

urn:oracle:webcenter:people:person:listName

The listName response contains the names of connections lists and URIs for use in accessing the connections lists.

Navigation Paths to listName

This section shows how the client can navigate through the hypermedia to access the listName resource:

resourceIndex
   person
      listNames
         listName

Writable Elements for listName

Table 42-12 lists the writable elements for the listName resource.

Table 42-12 Writable Elements for listName

Element	Type	Required	Constraints	Description
`name`	String	Yes	1 or more characters	A single list name

Resource Types Linked to from listName

Table 42-13 lists the resource types that the client can link to from the listName resource.

Table 42-13 Related Resource Types for listName

rel	resourceType
self urn:oracle:webcenter:people:person:list	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream:list	urn:oracle:webcenter:activities:stream

urn:oracle:webcenter:people:person:list:member

The member response contains URIs for use in deleting a connection from a connections list.

Navigation Paths to member

This section shows how the client can navigate through the hypermedia to access the member resource:

resourceIndex
   person
      list
         member

Supported Methods for member

The following method is supported by the member resource:

DELETE
- request

Writable Elements for member

Table 42-14 lists the writable elements for the member resource. Writable elements for member are used when you add a connection to a list or invite a user to be a connection. The member resource itself is for deleting connections, and does not use writable elements.

Table 42-14 Writable Elements for member

Element Type Required Constraints Description

Element	Type	Required	Constraints	Description
`guid`	String	Yes	1 or more characters	GUID of the user
`message`	String	No	0 or more characters	Invitation message Use this only when inviting users to be connections (that is POSTing to the `@connections` list, not to user-created connections lists).

guid

String

Yes

1 or more characters

GUID of the user

message

String

0 or more characters

Invitation message

Use this only when inviting users to be connections (that is POSTing to the @connections list, not to user-created connections lists).

urn:oracle:webcenter:people:person:status

The status response contains URIs for use in retrieving (GET) and updating (PUT) the profile status message of a specified user.

Navigation Paths to status

This section shows how the client can navigate through the hypermedia to access the status resource:

resourceIndex
   people
      person
         status

Supported Methods for status

The following methods are supported by the status resource:

GET
- request
- response—Body: status
PUT
- request—Body: status
- response—Body: status

Writable Elements for status

Table 42-15 lists the writable elements for the status resource.

Table 42-15 Writable Elements for status

Element	Type	Required	Constraints	Description
`note`	String	Yes	1 or more characters	Content of status message

Resource Types Linked to from status

Table 42-16 lists the resource types that the client can link to from the status resource.

Table 42-16 Related Resource Types for status

rel	resourceType
self	urn:oracle:webcenter:people:person:status

urn:oracle:webcenter:people:invitations

The invitations response contains URIs for use in retrieving invitations (GET). You can also send an invitation (POST) to another user.

Navigation Paths to invitations

This section shows how the client can navigate through the hypermedia to access the invitations resource:

resourceIndex
   invitations

If you are not already connected to a user, you can also navigate to the invitations resource from that user's profile in order to invite them to connect. This path is only used for POSTing.

resourceIndex
   person
      invitations

Supported Methods for invitations

The following methods are supported by the invitations resource:

GET
- Request—Parameters: q
  
  To retrieve invitations sent to the current user, the format of q is:
```
q=[invitee:equals:@me]
```
  To retrieve invitations sent from the current user, the format of q is:
```
q=[invitor:equals:@me]
```
- Response—Body: 1 or more invitations
POST
- Request—Body: invitation
- Response—Body: invitation

Writable Elements for invitations

Table 42-17 lists the writable elements for the invitations resource.

Table 42-17 Writable Elements for invitations

Element	Type	Required	Constraints	Description
`message`	String	No	1 or more characters	Message attached to the invitation

Resource Types Linked to from invitations

Table 42-18 lists the resource types that the client can link to from the invitations resource:

Table 42-18 Related Resource Types for invitations

rel	resourceType
self	urn:oracle:webcenter:people:invitation

urn:oracle:webcenter:people:invitation

The invitation response contains URIs for use in deleting (DELETE) invitations you have sent, or deleting (DELETE) or updating (PUT) invitations you have received.

Navigation Paths to invitation

This section shows how the client can navigate through the hypermedia to access the invitation resource:

resourceIndex
   invitations
      invitation

Supported Methods for invitation

The following methods are supported by the invitation resource:

PUT
- Request—Body: invitation
- Response—Body: invitation
DELETE
- Request

Writable Elements for invitation

Table 42-19 lists the writable elements for the invitation resource.

Table 42-19 Writable Elements for invitation

Element Type Required Constraints Description

Element	Type	Required	Constraints	Description
`status`	String	Yes (PUT)	ACCEPTED IGNORED	The status of the invitation. Note: When you accept or ignore an invitation, it is removed from your list of invitations.

status

String

Yes (PUT)

ACCEPTED

IGNORED

The status of the invitation.

Note: When you accept or ignore an invitation, it is removed from your list of invitations.

Read-only Elements for invitation

Table 42-20 lists the read-only elements for the invitation resource.

Table 42-20 Read-only Elements for invitation

Element	Type	Description
`id`	String	Unique ID of the invitation
`invitee`	personReference	User to whom the invitation is sent
`invitor`	personReference	User from whom the invitation is sent
`sentDate`	Date (String)^Foot 1	Date the invitation was sent

^Footnote 1Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

Resource Types Linked to from invitation

Table 42-21 lists the resource types that the client can link to from the invitation response.

Table 42-21 Related Resource Types for invitations

rel	resourceType
self	urn:oracle:webcenter:people:invitation

42.3 Feedback REST APIs

Use the Feedback REST APIs to read and delete feedback. This section provides information about the REST APIs to use to perform these actions. It includes the following subsections:

Section 42.3.1, "Feedback Entry Point"
Section 42.3.2, "Feedback Resource Type Taxonomy"
Section 42.3.3, "Feedback Security Considerations"
Section 42.3.4, "Feedback Resource Types"

42.3.1 Feedback Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the People Connections service, each feature has its own link element. To find the entry points for the Feedback feature of the People Connections service, find the link elements with a resourceType of:

urn:oracle:webcenter:feedback

The corresponding href or template element provides the URI entry point, which returns all received feedback for the current user. The client sends HTTP requests to this entry point to work with the Feedback feature of the People Connections service.

See Also:

For more information about the Resource Index, see Section 54.5.1, "The Resource Index."

For more information about resource types, see Section 54.5.2.1, "Resource Type."

42.3.2 Feedback Resource Type Taxonomy

the resource type taxonomy for the Feedback feature of the People Connections service is:

urn:oracle:webcenter:feedback
   urn:oracle:webcenter:feedback:message

42.3.3 Feedback Security Considerations

You must be logged in to the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Section 54.8, "Security Considerations for WebCenter Portal REST APIs."

42.3.4 Feedback Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

"urn:oracle:webcenter:feedback"
"urn:oracle:webcenter:feedback:message"

urn:oracle:webcenter:feedback

The feedback response contains URIs for use in reading Feedback messages.

Navigation Paths to feedback

This section shows how the client can navigate through the hypermedia to access the feedback resource:

resourceIndex
   feedback

resourceIndex
   person
      feedback

Supported Methods for feedback

The following methods are supported by the feedback resource:

GET
- request—Parameters: startIndex, itemsPerPage
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see "Common Request Query Parameters".
- response—Body: message
  
  See Also:
  
  For information about message, see "urn:oracle:webcenter:feedback:message".
POST – If permitted, lets you add feedback for a target user. This method is only available if the current user is connected to and has permission to add feedback for the target user.
- request - body: feedback
```
<message resourceType="urn:oracle:webcenter:feedback:message">
    <body>test from REST API</body>
    <receivedUser>
    <guid>4F16DD80393611DFBF895F177662C511</guid>
    </receivedUser>
</message>
```

Resource Types Linked to from feedback

Table 42-22 lists the resource types that the client can link to from the feedback resource.

Table 42-22 Related Resource Types for feedback

rel	resourceType
self urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback
self urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
	urn:oracle:webcenter:feedback:message

urn:oracle:webcenter:feedback:message

The message response contains the feedback message data and URIs for use in deleting a Feedback message.

Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access the message resource:

resourceIndex
   feedback
      message

resourceIndex
   person
      feedback
         message

Supported Methods from message

The following method is supported by the message resource:

DELETE
- request

Read-only Elements for message

Table 42-23 lists the read-only elements for the message resource.

Table 42-23 Read-only Elements for message

Element	Type	Description
`body`	String	Message content
`id`	String	Unique ID of the message
`author`	personReference	User who created the message
`created`	Date (String)^Foot 1	Date the message was created
receivedUser	personReference	A person reference to the user who received the feedback

^Footnote 1Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

Resource Types Linked to from feedback

Table 42-24 lists the resource types that the client can link to from the feedback resource.

Table 42-24 Related Resource Types for message

rel	resourceType
self	urn:oracle:webcenter:feedback:message

42.4 Message Board REST APIs

Use the Message Board REST APIs to post, read, and delete messages to a user's or a space message board.

This section provides information about the REST APIs to use to perform these actions. It includes the following subsections:

Section 42.4.1, "Message Board Entry Point"
Section 42.4.2, "Message Board Resource Type Taxonomy"
Section 42.4.3, "Message Board Security Considerations"
Section 42.4.4, "Message Board Resource Types"

42.4.1 Message Board Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the People Connections service, each feature has its own link element. To find the entry points for the Message Board feature of the People Connections service, find the link elements with a resourceType of:

urn:oracle:webcenter:messageBoard

Note:

As well as an entry point from the Resource Index, to navigate to an individual user's message board, the Message Board feature also has an entry point from a space response for the space message board.

The corresponding href or template element provides the URI entry point, which returns the Message Board for the current user. The client sends HTTP requests to this entry point to work with the Message Board feature of the People Connections service.

See Also:

For more information about the Resource Index, see Section 54.5.1, "The Resource Index."

For more information about resource types, see Section 54.5.2.1, "Resource Type."

42.4.2 Message Board Resource Type Taxonomy

The resource type taxonomy for the Message Board feature of the People Connections service is:

urn:oracle:webcenter:messageBoard
   urn:oracle:webcenter:messageBoard:message

42.4.3 Message Board Security Considerations

You must be logged in to the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Section 54.8, "Security Considerations for WebCenter Portal REST APIs."

42.4.4 Message Board Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

"urn:oracle:webcenter:messageBoard"
"urn:oracle:webcenter:messageBoard:message"

urn:oracle:webcenter:messageBoard

The messageBoard response contains URIs for use in reading (GET) and posting (POST) space and individual user Message Board messages.

Navigation Paths to messageBoard

This section shows how the client can navigate through the hypermedia to access the messageBoard resource:

resourceIndex
   messageBoard

resourceIndex
   person
      messageBoard

resourceIndex
   spaces
      space
         messageBoard

Supported Methods for messageBoard

The following methods are supported by the messageBoard resource:

GET
- request—Parameters: startIndex, itemsPerPage
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see "Common Request Query Parameters".
- response—Body: message
Note:

The REST GET command for reading (retrieving) messages retrieves all shown messages. Messages that are hidden through the application user interface are not retrieved. For information about hiding and showing messages, see "Working with Message Board Task Flows," in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.
POST
- request—Body: message
  
  The POST for messages supports including a link URL in the message.
  
  See Also:
  
  For information about message, see "urn:oracle:webcenter:messageBoard:message".

Read-only Elements for messageBoard

Table 42-25 lists the read-only elements for the messageBoard resource.

Table 42-25 Read-only Elements for message

Element	Type	Description
`messageType`	String	Returns `link` if the message has a link. Otherwise, returns `null`.
`link`	String	Contains link data for messages with links: `name`, `url`, `icon`, `description`, `mimeType`, `objectId`, `objectType`, `serviceId`.

Resource Types Linked to from messageBoard

Table 42-26 lists the resource types that the client can link to from the messageBoard resource.

Table 42-26 Related Resource Types for messageBoard

rel	resourceType
self	urn:oracle:webcenter:messageBoard
	urn:oracle:webcenter:messageBoard:message

urn:oracle:webcenter:messageBoard:message

The message response contains the Message Board message data and URIs for use in reading (GET), revising (PUT), and deleting (DELETE) a space or individual user Message Board message.

Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access the message resource:

resourceIndex
   messageBoard
      message

resourceIndex
   person
      messageBoard
         message

resourceIndex
   spaces
      space
         messageBoard
            message

Supported Methods for message

The following methods are supported by the message resource:

GET
- request
- response—Body: message
PUT
- request—Body: message
- response—Body: message
DELETE
- request

Writable Elements for message

Table 42-27 lists the writable elements for the message resource.

Table 42-27 Writable Elements for message

Element	Type	Required	Constraints	Description
`body`	String	Yes	1 or more characters	message content

Read-only Elements for message

Table 42-28 lists the read-only elements for the message resource.

Table 42-28 Read-only Elements for message

Element	Type	Description
`id`	String	Unique ID of the message
`author`	personReference	User who created the message
`created`	Date (String)^Foot 1	Date the message was created

^Footnote 1Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

Resource Types Linked to from message

Table 42-29 lists the resource types that the client can link to from the message resource.

Table 42-29 Related Resource Types for message

rel	resourceType
self	urn:oracle:webcenter:messageBoard:message

42.5 Creating an Invitation

This section illustrates how to invite another user to join your connections list using the People Connections Service REST API. After the invitation is made, the invitee is given the option to accept or not. This example also illustrates how to delete an invitation.

This section includes the following subsections:

Section 42.5.1, "Creating an Invitation"
Section 42.5.2, "Deleting an Invitation"

42.5.1 Creating an Invitation

The first step, as always with the REST APIs, is to retrieve the resource index:
```
GET http://<host:port>/rest/api/resourceIndex
```
Next, find the person to whom you want to connect. To do this:
1. In the resource index listing, scan for the link with the following resource type:
```
urn:oracle:webcenter:people:person
```
2. Execute a search for the user who you wish to invite. In this example, the user is named Monty.
```
GET http://<host:port>/rest/api/people?q=loginid:equals:monty&utoken=ASDF
```
3. Locate Monty's GUID in the response, as shown in Figure 42-1.
  
  Figure 42-1 Response With User's GUID
  
  Description of "Figure 42-1 Response With User's GUID"
4. Save the GUID so that you can use it to connect to the user.
Now that you have the invitee's GUID, you must find the resource to which you would like to add him. In this case, you want to add him to your own connections list.

To find your connections list, first, scan the People Connections documentation (this chapter) for "connections." You will discover in Table 42-9, "Related Resource Types for person" that connections are linked to from the person resource. For convenience, this table is shown in Figure 42-2.

Figure 42-2 Finding the connections Link

Description of "Figure 42-2 Finding the connections Link"

Now that you know that connections are linked to from the person resource, you need to find the person resource. As the URN indicates, you get to the person resource from the people resource, as described in the following steps.
Return to the resource index (or use a cached version of the resourceIndex from your previous visit):
```
GET http://<host:port>/rest/api/resourceIndex
```
Scan for the people resource, and you will find:
```
urn:oracle:webcenter:people
```

Use the link in the people resource to access your lists:

GET http://<host:port>/rest/api/people/@me/lists/@self?utoken=ASDF

Scan the returned links for the resourceType and rel listed in Table 42-9:

resourceType="urn:oracle:webcenter:people:person:list
rel="urn:oracle:webcenter:people:person:list:connections

Make the invitation by using the URI to your connections list to execute a POST:

POST http://<host:port>/rest/api/people/@me/lists/@connections?utoken=ASDF
 
Headers --  Accept:application/json, Content-Type:application/json
Body -- {"message":"Monty, do you want to join my connections list?","guid":"1AE5AF102E2611E09F062B573E287934"}

Now, if you log in to Monty's account and you can see the invitation has been added, as shown in Figure 42-3.

Figure 42-3 Activity Stream Showing Invitation

Description of "Figure 42-3 Activity Stream Showing Invitation"

42.5.2 Deleting an Invitation

After you initiate an invitation, you can view the invitation from your account by specifying invitor:equals:@me. For example:

GET http://<host:port>/rest/api/people/invitations?q=invitor:equals:@me&utoken=ASDF

Each invitation element listed in the response contains a link that supports the DELETE operation and that looks something like this:

<links>
<link resourceType="urn:oracle:webcenter:people:invitation" 
rel="self"
href="http://host_name:port_name/rest/api/people/invitations/
   e9073cdb-56ab-423d-8b1f-1220c802bdd4?
   utoken="FN0SEFwX42OCntwtx9a1dSbhqocO_w**" 
   capabilities="urn:oracle:webcenter:delete"/>
</links>

The invitee can also delete an invitation from his or her own account. The invitee can get a list of his or her invitations by specifying:

GET http://<host:port>/rest/api/people/invitations?q=invitee:equals:@me&utoken=ASDF

Note that the response from a DELETE is simply a status code of 204.