Reference : REST XML API reference : Element collection
  
Element collection
An element collection has the contents of a view or module. The URI for an element collection is available in the service document and the general URI is:
http://focalpointserver/context/resources/workspaces/1/modules/1/elements/
The XML representation of the element collection contains a URI for each element in the element collection. Depending on the link that was chosen in the service document, the collection might include attribute values and might be structured as tree or a flat list.
A single element contains all attribute values and contains more details than the collection. The XML format for the element collection is defined by the XML Schema document in the schemaLocation XML attribute. The XML Schema is unique for each view and module, and dynamically reflects the attribute setup of the module or view. The schema might change in these situations:
▪ an attribute is added, removed, or changed
▪ a view definition is changed
▪ a module is renamed.
If a collection is an add view or a module, you can add an element to the collection by using POST operation. The body of the request must contain an XML representation of the element. The XML format to use is in the XML Schema for the collection. If the collection is an add view, the contents of the view are in the folders. The folders can be parents when a new element is added.
Note RESTful APIs ignore the filters that are applied in views. All the elements of a view are displayed.The resource URI for the service document is:
http://focalpointserver/fp/resources/
GET method
Use this method to retrieve the collection of elements in a module. You can use the View parameter to filter the elements and attributes.
URL
https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/.xml?includeAttributes=true&view=14
Accept header
application/xml
Response body
<ns:elementCollection xsi:schemaLocation="https://fpserver.com:9443/fp/namespace/workspaces/2/modules/1/views/14/elements https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements.xsd?view=14"> <ns:Elements count="1"> <ns:Element> <ns:attributes> <ns:Element_Information/> <ns:ID></ns:ID> <ns:Title></ns:Title> <ns:Description></ns:Description> <ns:type_is_a_folder> </ns:type_is_a_folder> </ns:attributes> <ns:selfLink href="https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/15?view=14"/> <ns:alias>38bfbaaa-6af2-49ed-a6f4-d0cf39704a55</ns:alias> </ns:Element></ns:Elements> <fp:link href="https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/?view=14" rel="alternate"/> <fp:link href="https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/?view=14&includeAttributes=true&tree=true" rel="alternate"/> <fp:link href="https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/?view=14&tree=true" rel="alternate"/></ns:elementCollection>
Supported parameters for the GET method
 
Parameter
Description
includeAttributes
Set this parameter to true to retrieve the attributes of the elements.
Type: Boolean
view
Use this parameter to specify the view ID for retrieving the elements or attributes that are in the view.
Type: Integer
filter
This must be used with the view parameter. Use this parameter to pass the filter ID for retrieving elements and attributes based on the filter criteria.
Type: Integer
Example
view=14&filter=1
tree
Set this parameter to view the element collection in the tree structure
Type: Boolean
modifiedSince
Use this parameter to retrieve the element that have changed since a specified date. The following formats are supported.
Note: The user can also supply modifiedsince as a parameter.
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd'T'HH:mm
yyyy-MM-dd
yyyy-MM-dd HH:mm:ss
yyyy-MM-dd HH:mm
Type: Date or DateTime
Example
2013-04-19T15:16:38+05:30
2009-01-22T12:00:00+01:00
metadata
Set the parameter to schema to retrieve the schema of the element collection’s XML document
Type: String
Example
metadata=schema
fields
Use this parameter to pass XPath expression to retrieve specific set of attributes or to filter elements based on specific values of attributes.
Type: XPath expression
Example: To retrieve a specific set of attributes
fields=elementCollection/Element/attributes/(ID|Title|Owner)
Example: To filter elements based on attribute values
fields=elementCollection/Element/attributes/(Title contains X OR Status is Approved )
fields=elementCollection/Element/attributes/(Title = X | Status is Approved )
fields=elementCollection/Element/attributes/(Title is X AND Status = Approved )
fields=elementCollection/Element/attributes/(Title contains X AND Cost < 100 )
See Notes for fields parameter
paging, pageSize, pageNo
Use these parameters to retrieve the collection of elements that are paginated. When pagination is enabled the XML document shows an additional link to the next page.
Types
paging: Boolean
pageSize: Integer
Note: The user can also supply pagesize as a parameter.
pageNo: Integer
Note: The user can also supply pageno as a parameter.
Examples
<fp:link href="https://fpserver.com:9443/fp/resources/workspaces/2/modules/1/elements/?pageno=1&pageSize=2&paging=true&includeAttributes=true" rel="next" Page="0"/>
paging=true&pageSize=2&pageNo=1
includeHistoryOfAttributes, start, end
Set the parameter to “true”, and then specify the start and the end date to retrieve the history of the attributes.
▪ yyyy-MM-dd'T'HH:mm:ss
▪ yyyy-MM-dd'T'HH:mm
▪ yyyy-MM-dd
▪ yyyy-MM-dd HH:mm:ss
▪ yyyy-MM-dd HH:mm
Types
includeHistoryOfAttributes: Boolean
start: Date or Date Time
end: Date or Date time
Examples
includeHistoryOfAttributes=true&start=2011-03-22T12:00:00+01:00&end=2011-06- 22T12:00:00+01:00
includeHistoryOfAttributes=true&start=2011-03-22T12:00+GMT+01:00&end=2011-06-22T12:00+GMT+01:00
genericTimeGrid
Set the parameter to true for retrieving the time grid attribute sheets in a generic format. This can be used for reporting using Rational Insight.
Note: The user can also supply generictimegrid as a parameter.
Type: Boolean
Example
genericTimeGrid=true
optimize
Set the parameter to true to optimize the content. If this is set to true, the response will not include rich text and formula information of the attributes. Also alternate urls to the element will not be provided in the response.
Type: Boolean
Example
optimize=true
includeLinkTable
Set the parameter to true to include attributes from the link targets in the response. The view should have a link table defined for the link/link list attributes. All visible attributes shown in the link table set up will be part of the link/linklist attribute response.
Type: Boolean
Example
includeLinkTable=true
sortID
Use this parameter to sort the elements in the collection based on an attribute in the view. Provide the id of the attribute as the value for the parameter.
Type: Integer
Example
sortID=100
descending
Use this parameter to sort the elements in the collection in descending order. If this parameter is not specified, sorting will be done in ascending order.
Type: Boolean
Example
descending=true
Notes for fields parameter
▪ Attribute names and the attribute values should be enclosed in single quotes if they contain the following special characters:
(, ), <, >, |, =
If the names or values already contain single quotes (') then they need to be escaped with a backslash as: \'
Example: fields=elementCollection/Element/attributes/('Comments(incl)' contains 'Shift>Technology')
▪ The following characters or character sequences can be used as operators:
=, <, >, is, contains
▪ Different filtering conditions can be connected using the following connectors (case sensitive):
AND, OR, | (same as OR)
▪ If you are using the fields parameter for filtering the elements, avoid providing modifiedSince parameter. Instead use the fields parameter with a filtering condition specified on Last Changed Date attribute.
▪ Only the following types of attributes are supported for specifying the filtering conditions: Text, Integer, Float, Date, Choice, Check Box, MulitChoice, Parent Folder, Created Date, Created By, Last Changed Date, Last Changed By, Owner, Link, Linklist, Incoming Link, Unique Id.
▪ For attributes like Choice and MultiChoice you can specify the name of the items as the filtering value. For Link, Linklist and Incoming Link you need to specify the id of the target element as the filtering condition. For Parent Folder, Owner, Created By and Last Modified by attributes you can either specify the name or id of the target element.
▪ To filter based on more than one attribute value, provide the filtering condition by comma-separating the individual values.
Example: fields=elementCollection/Element/attributes/(Geography contains Asia,Europe)
This will filter the elements whose Geography contains both Asia and Europe (applies 'all' condition).
For multivalued attributes like MultiChoice and Linklist you can prefix the filtering condition with or, to specify the 'any' condition while filtering.
Example: fields=elementCollection/Element/attributes/(Geography contains or,Asia,Europe)
This will filter the elements whose Geography contains either Asia or Europe (applies 'any' condition).
▪ For parent folder attribute prefix the filtering condition with r, to set recursive rule.
Example: fields=elementCollection/Element/attributes/(Parent Folder is r,System)
This will filter all elements whose parent folder is System or any of its subfolders.
For details and annotations of the XML format for the service document, see the XML Schema document. The URI for the schema is in the schemaLocation XML attribute of the service document.
POST method
Use this method to create new element to a module. Non-administrators can use view parameters to create. This example is on using the POST method to create new elements. The user must have administrator permission for creating elements in the module.
Example on using the POST method to create elements
URL
https://fpserver.com:9443/fp/resources/workspaces/3/modules/1/elements/.xml
Accept header
application/xml
Request body
<ns:newElement xmlns:ns="https://fpserver.com:9443/fp/namespace/workspaces/3/modules/1/elements" xmlns:fp="http://schema.ibm.com/focalpoint/resources" > <ns:Title> <fp:textValue xmlns:fp="http://schema.ibm.com/focalpoint/resources">karthi 1</fp:textValue> </ns:Title> <ns:MealPreference value="NonVeg"></ns:MealPreference> <ns:type_is_a_folder value="true"></ns:type_is_a_folder> <ns:Comments> <ns:newTextListEntry> <fp:textValue xmlns:fp="http://schema.ibm.com/focalpoint/resources">text entry 1</fp:textValue> </ns:newTextListEntry> <ns:newTextListEntry> <fp:textValue xmlns:fp="http://schema.ibm.com/focalpoint/resources">text entry 2</fp:textValue> </ns:newTextListEntry> </ns:Comments> <ns:RelatedReleases> <fp:linkChange value="https://fpserver.com:9443/fp/resources/workspaces/3/modules/3/elements/40"></fp:linkChange> <fp:linkChange value="https://fpserver.com:9443/fp/resources/workspaces/3/modules/3/elements/41"></fp:linkChange> </ns:RelatedReleases><ns:Parent_Folder value="https://fpserver.com:9443/fp/resources/workspaces/3/modules/1/elements/61"></ns:Parent_Folder> </ns:newElement>
The root node <ns:newElement> is based on the module name. For example: if the module name is products, then the new element is product.
Supported parameters for the POST method
 
Parameter
Type
optimize
Set this parameter to true to optimize element creation.
 
Type: Boolean
This example uses the POST method to create new elements using a view. The non-administrator can add elements to the module using the views.
Example on using the POST method to create elements using views1
 
URL
https://fpserver.com:9443/fp/resources/workspaces/3/modules/1/elements/.xml?view=200&optimize=true
Accept header
application/xml
Request body
<ns:newElement xmlns:ns="https://fpserver.com:9443/fp/namespace/workspaces/3/modules/1/views/200/elements" xmlns:fp="http://schema.ibm.com/focalpoint/resources" > ... </ns:newElement>
The root node (<ns:newElement>) is based on the module name. For example: if the module name is products, then the new element is product.
Multipart POST: This example uses the POST method to update multiple attributes through one HTTP request. The content type for this request is multipart/related. You can only use the POST method only to add links, delete links of an element.
 
URL
https://fpserver.com:9443/fp/resources/workspaces/5/modules/1/elements/.xml
Accept header
application/xml
Content type
multipart/related
Request body
<attributeChangeCollection xmlns:ns="https://schema.com/focalpoint/resources" > <linkListChange href="/14/attributes/224"> <ns:addLink value="https://fpserver.com:9443/fp/resources/workspaces/5/modules/3/elements/20"></ns:addLink> <ns:addLink value="https://fpserver.com:9443/fp/resources/workspaces/5/modules/3/elements/19"></ns:addLink> <ns:deleteLink value="https://fpserver.com:9443/fp/resources/workspaces/5/modules/3/elements/18"></ns:deleteLink> </linkListChange> <textListEntryChange href="./14/attributes/223/entries/" > <ns:textValue>one</ns:textValue> </textListEntryChange> </attributeChangeCollection >
PUT method
Multipart PUT: This example is on using the PUT method to update multiple attributes through one HTTP request. The content type for this request is multipart/related.
 
URL
http://fpserver.com:9443/fp/resources/workspaces/5/modules/1/elements/.xml
Accept header
application/xml
Content type
multipart/related
Request body
<attributeChangeCollection xmlns:ns="http://schema.com/focalpoint/resources"> <textAttributeChange href="./14/attributes/2"> <ns:textValue>new text value</ns:textValue> </textAttributeChange> <textAttributeChange href="./15/attributes/2"> <ns:textValue>new text value</ns:textValue> </textAttributeChange> <textListEntryChange href="./14/attributes/223/entries/212309123" > <ns:textValue>replaced value</ns:textValue> </textListEntryChange> </attributeChangeCollection>
See also
REST XML API reference