AgileApps Support Wiki

REST API:globalPicklist Resource

From AgileApps Support Wiki
Revision as of 00:18, 23 October 2012 by imported>Aeric (Text replace - '{{permissions|Customize Objects|' to '{{permissionRef|Customize Objects|')

Manage Global Picklists using the REST API.

Learn more: REST API Conventions and Considerations.

Permissions

Lock-tiny.gif

Users that have the Customize Objects permission can create or edit a Global Picklist. 

List All Global Picklists

"List" of all global picklists defined in the platform. (For a given picklist, do an additional GET to retrieve the enumeration values.)

Method
GET
URI
https://{yourDomain}/networking/rest/globalPicklist
Return all fields
Response

Here is a sample that shows some of the predefined global picklists available in the platform:

<syntaxhighlight lang="xml" enclose="div">

<platform> 

 <globalPickList>
   <id>115463636</id>
   <title>Countries</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
 </globalPickList>

 <globalPickList>
   <id>1739225993</id>
   <title>US States (state name)</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
 </globalPickList>

 <globalPickList>
   <id>316671085</id>
   <title>US States (2 letter abbrev)</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
 </globalPickList> 

  ...

 <globalPickList>
   <id>case_status</id>
   <title>Case Status</title>
   <description>Displays Case Status</description>
   <showFirstValueAsDefault>true</showFirstValueAsDefault>
   <sortFlag>false</sortFlag>
 </globalPickList>

 <globalPickList>
   <id>case_type</id>
   <title>Case Type</title>
   <description>Displays Case Type</description>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
 </globalPickList>
 
  ...
  
 <globalPickList>
   <id>salutation</id>
   <title>Salutation</title>
   <description>How emails should be addressed</description>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>false</sortFlag>
 </globalPickList> 
 
  ...
  
 <globalPickList>
   <id>task_priority</id>
   <title>Task Priority</title>
   <description>Displays task priority</description>
   <showFirstValueAsDefault>true</showFirstValueAsDefault>
   <sortFlag>false</sortFlag>
 </globalPickList>

 <globalPickList>
   <id>task_status</id>
   <title>Task Status</title>
   <description>Displays current status of task</description>
   <showFirstValueAsDefault>true</showFirstValueAsDefault>
   <sortFlag>false</sortFlag>
 </globalPickList>

 <message>
   0
   <description>Success</description>
 </message>
 <recordCount>29</recordCount>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Get a Global Picklist

Method
GET
URI
https://{yourDomain}/networking/rest/globalPicklist/{recordId}
Response

This query gets the global picklist of U.S. States:

The response looks like this:

<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <globalPicklist>
   <date_created>2007-07-24T19:06:02.000Z</date_created>
   <date_modified>2007-07-24T19:06:02.000Z</date_modified>
   <created_id type="USER" 
      uri="https://{domain}/networking/rest/user/3" 
      displayValue=" System">3</created_id>
   <modified_idtype="USER" 
      uri="https://{domain}/networking/rest/user/3" 
      displayValue=" System">3</modified_id>
   
   <id>316671085</id>
   <title>US States (2 letter abbrev)</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
   <allowSubscriberToAdd>false</allowSubscriberToAdd>
   <allowSubscriberToDelete>false</allowSubscriberToDelete>
   <allowSubscriberToModify>false</allowSubscriberToModify>

   <enumerationItems>
     <id>8d27255e164d102db40712313a00ce07</id>
     <picklistLabel>AL</picklistLabel>
     <picklistValue>AL</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <dateCreated>2007-07-24T19:06:02.000Z</dateCreated>
     <dateModified>2007-07-24T19:06:02.000Z</dateModified>
     <itemOrder>0</itemOrder>
   </enumerationItems>

   <enumerationItems>
     <id>8d272d4c164d102db40712313a00ce07</id>
     <picklistLabel>AK</picklistLabel>
     <picklistValue>AK</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <dateCreated>2007-07-24T19:06:02.000Z</dateCreated>
     <dateModified>2007-07-24T19:06:02.000Z</dateModified>
     <itemOrder>1</itemOrder>
   </enumerationItems>
   
    ...
    
   <enumerationItems>
     <id>8d2ae824164d102db40712313a00ce07</id>
     <picklistLabel>WY</picklistLabel>
     <picklistValue>WY</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <dateCreated>2007-07-24T19:06:02.000Z</dateCreated>
     <dateModified>2007-07-24T19:06:02.000Z</dateModified>
     <itemOrder>58</itemOrder>
   </enumerationItems>
   </globalPicklist>
   
   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Add a Global Picklist

Method
POST
URI
https://{yourDomain}/networking/rest/globalPicklist
Request
<syntaxhighlight lang="xml" enclose="div">

<platform> 

 <globalPicklist>
   <title>Shipping Method</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
   <allowSubscriberToAdd>true</allowSubscriberToAdd>
   <allowSubscriberToDelete>false</allowSubscriberToDelete>
   <allowSubscriberToModify>true</allowSubscriberToModify>

   <enumerationItems>
     <picklistLabel>UPS</picklistLabel>
     <picklistValue>UPS</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <itemOrder>1</itemOrder>
   </enumerationItems>
   
   <enumerationItems>
     <picklistLabel>First Class</picklistLabel>
     <picklistValue>FIRST</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <itemOrder>2</itemOrder>
   </enumerationItems>
 </globalPicklist>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>066aedc3e0fc4c28879951e7164b1fde</id>  
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update a Global Picklist

Method
PUT
URI
https://{yourDomain}/networking/rest/globalPicklist/{recordId}
Request

This example uses the result of a previous GET to add a third entry to the shipping method picklist. The GET returns a list of two enumeration values, with their IDs. Including them in the update request keeps them intact. (The new list replaces the old. ID fields, if present, are ignored.)

<syntaxhighlight lang="xml" enclose="div">

<platform> 

 <globalPicklist>
   <title>Shipping Method</title>
   <description/>
   <showFirstValueAsDefault>false</showFirstValueAsDefault>
   <sortFlag>true</sortFlag>
   <allowSubscriberToAdd>true</allowSubscriberToAdd>
   <allowSubscriberToDelete>false</allowSubscriberToDelete>
   <allowSubscriberToModify>true</allowSubscriberToModify>

   <enumerationItems>                            
     <picklistLabel>UPS</picklistLabel>
     <picklistValue>UPS</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <itemOrder>1</itemOrder>
   </enumerationItems>

   <enumerationItems>                            
     <picklistLabel>First Class</picklistLabel>
     <picklistValue>FIRST</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <itemOrder>2</itemOrder>
   </enumerationItems>
     
   <enumerationItems>                            
     <picklistLabel>FedEx</picklistLabel>
     <picklistValue>FEDEX</picklistValue>
     <textColor>#000000</textColor>
     <textBgColor>#FFFFFF</textBgColor>
     <showOnlyImage>false</showOnlyImage>
     <flagIsOptgroup>false</flagIsOptgroup>
     <itemOrder>3</itemOrder>
   </enumerationItems>   
  
 </globalPicklist>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a Global Picklist

Method
DELETE
URI
https://{yourDomain}/networking/rest/globalPicklist/{recordId}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Dynamic Search for Global Picklists

Method
GET
URI
https://{yourDomain}/networking/rest/globalPicklist?{query_parameters}
Sample Search
?fieldList=name,id & filter=name contains 'smith' & sortby='id'
(Field names are in the Fields section.)
Query Parameters
  • fieldList - A comma-separated list of field names to retrieve
  • The asterisk (*) wildcard specifies all fields
  • {fieldname} specifies an individual field (e.g. name)
(Use the REST API:field Resource to get a complete list of fields.)
  • For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
  • For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
  • alias.* specifies all fields in the aliased object.
  • filter - Filtering criteria to filter the records
  • pageSize - Number of records to retrieve from the result set in order to make a "page".
  • page - Number of the logical page in a database result set. The first page is page "zero" (0).
Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.
  • getTotalRecordCount returns the number of total records.
    Causes the following structure to be returned, where N is the total number of records:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

  <status>
  <packageDeploy>
  ...
  </packageDeploy>
  </status>
  <message>
     0
     <description>Success</description>
  </message>

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • sortBy - Field name for primary sort
    Ex: &sortBy=name
  • sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
    Ex: &sortOrder=desc
  • sortBy2 - Field name for secondary sort
  • sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)
For more information, see: Specifying Query Parameters in REST APIs


Response
<syntaxhighlight lang="xml" enclose="div">
   ....
   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".

Global Picklist Fields:

Name Type Attribute Required on Add Description Additional Information
id String Read Only Record Id
title String Checkmark.gif User friendly title for the Picklist
description String Checkmark.gif Description of the Picklist
showFirstValueAsDefault boolean Checkmark.gif If true, the first value in the picklist is shown as selected by default. If false, a blank value is shown as the default.
sortFlag boolean Checkmark.gif If true, picklist values are displayed in alphabetical order. If false, the values are shown in the order determined by the itemOrder settings in the Enumeration fields. (When values are missing or identical, values or shown in the order in which they were entered.)
allowSubscriberToAdd boolean Checkmark.gif If the picklist was created as a result of a subscribed package, this flag decides if subscribers will be able to add items to the Picklist.
allowSubscriberToDelete boolean Checkmark.gif If the picklist was created as a result of a subscribed package, this flag decides if subscribers will be able to delete Picklist items.
allowSubscriberToModify boolean Checkmark.gif If the picklist was created as a result of a subscribed package, this flag decides if subscribers will be able to modify Picklist items.
date_modified Date Read Only UTC Format
date_created Date Read Only UTC Format
created_id Lookup Read Only User ID
modified_id Lookup Read Only User ID

Enumeration Fields:

Name Type Attribute Required on Add Description Additional Information
id String Read Only Record Id
picklistLabel String Checkmark.gif User friendly label for the enumerated Picklist value. This label is displayed in the UI.
picklistValue String Checkmark.gif The value for the enumeration that is stored in the database. This value is returned in APIs that access Picklist fields.
textColor String Checkmark.gif HTML Color code for the Picklist label #000000 = Black
textBgColor String Checkmark.gif HTML Color code for the background which displays the Picklist label in the UI #FFFFFF = White
showOnlyImage boolean Checkmark.gif If an image is associated with the enumeration value, this flag decides if only the image is shown instead of being accompanied by the Picklist label.
(Reserved for future use)
flagIsOptgroup boolean Checkmark.gif Decides if the label should be used for grouping the Picklist values instead of being used as an enumerated vale. If true, the enumerated values below this will be shown as a group under the current entry.
itemOrder number Checkmark.gif A number that determines the order in which enumerated values are displayed. Typically starts with one or zero.
date_modified Date Read Only UTC Format
date_created Date Read Only UTC Format
created_id Lookup Read Only User ID
modified_id Lookup Read Only User ID
Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=REST_API:globalPicklist_Resource&oldid=12978"