Package com.veeva.vault.sdk.api.picklist

package com.veeva.vault.sdk.api.picklist

This package provides interfaces to retrieve picklist information.

Overview

The package provides services and interfaces to interact with picklists. The central entry point is the PicklistService, which allows retrieval of picklist metadata.

Useful Interfaces

• Picklist: Represents a single picklist component. This holds metadata on the picklist such as its public key, label, and whether it is controlled by another picklist, etc.
• PicklistValue: Represents a single picklist value component. This holds metadata on the picklist such as its public key, label, and order, etc.
• PicklistDependency: Represents the relationship between a controlling picklist value and its dependent values.

Requests and Responses

Generally, you would construct a request, execute it via PicklistService, and get a response containing data.

For retrieving picklists:

• PicklistRequest: A request used to retrieve a single Picklist object. Language and label set can be specified to retrieve the appropriate label needed.

For retrieving picklist values:

• PicklistValueMetadataCollectionRequest: A request to retrieve PicklistValue objects. The picklist public key must be specified and you can optionally:
  • Filter for values based on their public keys
  • Filter for values based on the controlling picklist
  • Include inactive values in addition to active values
  • Specify a language or label set for the labels
• PicklistValueMetadataCollectionResponse: A response containing the results of executing a PicklistValueMetadataCollectionRequest, holding the PicklistValue objects that matched the request criteria.

For retrieving picklist dependencies:

• PicklistDependencyMetadataCollectionRequest: A request to retrieve PicklistDependency objects. The picklist public key must be specified and you can optionally filter the results for controlling values.
• PicklistDependencyMetadataCollectionResponse: A response containing the results of executing a PicklistDependencyMetadataCollectionRequest, holding the PicklistDependency objects that matched the request criteria.

Example: Retrieve Picklist Metadata by Public Key

The following example illustrates retrieving picklist metadata using PicklistService.getPicklist(java.lang.String).

Note that this method will fetch the picklist label for the Vault base language (falling back to English if none exists). Use PicklistService.getPicklist(com.veeva.vault.sdk.api.picklist.PicklistRequest) in order for other languages and label sets to be considered

     
     PicklistService picklistService = ServiceLocator.locate(PicklistService.class);

     // retrieve picklist
     Picklist picklist = picklistService.getPicklist("test_picklist__c");
     if (picklist != null) {
         String publicKey = picklist.getName();
         String label = picklist.getLabel();
         boolean isSystemManaged = picklist.isSystemManaged();
         boolean hasControllingPicklist = picklist.hasControllingPicklist();
         String controllingPicklistPublicKey = picklist.getControllingPicklistName();
     }
     
 

Example: Retrieve Picklist Metadata by PicklistRequest

The following example illustrates retrieving picklist metadata using PicklistService.getPicklist(com.veeva.vault.sdk.api.picklist.PicklistRequest).

Note that this method will fetch the picklist label determined by the request. Refer to PicklistRequest.Builder.withLabelSet(java.lang.String) and PicklistRequest.Builder.withLanguage(java.lang.String) on how labels are determined and its fallback behavior.

     
     PicklistService picklistService = ServiceLocator.locate(PicklistService.class);

     // build request to retrieve picklist with public key
     PicklistRequest.Builder picklistRequest = picklistService.newPicklistRequestBuilder()
          .withName("test_picklist__c")
          .withLabelSet("commercial_fr__c") // optional
          .withLanguage("de") // optional
          .build();

      // retrieve picklist
      Picklist picklist = picklistService.getPicklist(picklistRequest);
      if (picklist != null) {
          String publicKey = picklist.getName();
          String label = picklist.getLabel();
          boolean isSystemManaged = picklist.isSystemManaged();
          boolean hasControllingPicklist = picklist.hasControllingPicklist();
          String controllingPicklistPublicKey = picklist.getControllingPicklistName();
      }
      
 

Example: Retrieve Picklist Value Metadata

The following example illustrates retrieving picklist value metadata using PicklistService.getPicklistValueMetadataCollection(com.veeva.vault.sdk.api.picklist.PicklistValueMetadataCollectionRequest). This method will fetch labels, status, and dependency information for multiple picklist values.

Refer to PicklistValueMetadataCollectionRequest.Builder.withLabelSet(java.lang.String) and PicklistValueMetadataCollectionRequest.Builder.withLanguage(java.lang.String) on how labels are determined and its fallback behavior.

     
     PicklistService picklistService = ServiceLocator.locate(PicklistService.class);

     // build request to retrieve all picklist values of a given picklist
     PicklistValueMetadataCollectionRequest valueRequest = picklistService.newPicklistValueMetadataCollectionRequestBuilder()
          .withPicklistName("test_picklist__c")
          .withLabelSet("commercial_fr__c") // optional
          .withLanguage("de") // optional
          .build();

     PicklistValueMetadataCollectionResponse valueResponse = picklistService.getPicklistValueMetadataCollection(valueRequest);

     // retrieves all picklist values in the response
     List<PicklistValue> allPicklistValues = valueResponse.getPicklistValues();

     // retrieves a specific picklist value
     PicklistValue picklistValue = valueResponse.getPicklistValue("test_picklist_value__c");
     if (picklistValue != null) {
          String publicKey = picklistValue.getName();
          boolean isActive = picklistValue.isActive();
          String label = picklistValue.getLabel();
          int order = picklistValue.getOrder();
          boolean hasControllingValues = picklistValue.hasControllingValues();
          List<String> controllingValuePublicKeys = picklistValue.getControllingValueNames();
     }
     
 

Example: Retrieve Picklist Dependency Metadata

The following example illustrates retrieving picklist dependency metadata using PicklistService.getPicklistDependencyMetadataCollection(com.veeva.vault.sdk.api.picklist.PicklistDependencyMetadataCollectionRequest).

     
     PicklistService picklistService = ServiceLocator.locate(PicklistService.class);

     // build request to retrieve dependency metadata for given picklist
     PicklistDependencyMetadataCollectionRequest dependencyRequest = picklistService.newPicklistDependencyMetadataCollectionRequestBuilder()
          .withPicklistName("test_picklist__c")
          .build();

     PicklistDependencyMetadataCollectionResponse dependencyResponse = picklistService.getPicklistDependencyMetadataCollection(dependencyRequest);

     // retrieves all picklist dependencies in the response
     List<PicklistDependency> dependencies = dependencyResponse.getDependencies();

     // retrieves picklist dependencies for the given controlling picklist value
     List<PicklistDependency> dependenciesForPicklistValue = dependencyResponse.getDependencies("controlling_picklist_value__c");

     for (PicklistDependency dependencies : dependency) {
          // retrieve public key of controlling picklist value
          String controllingPicklistValue = dependency.getControllingPicklistValueName();

          // retrieve list of public keys of dependent picklist values
          List<String> dependentPicklistValues = dependency.getPicklistValueNames();
     }
     
 

Best Practices & Gotchas

• Label Localization: Returned labels of picklists and picklist values are dependent on the method being used. To retrieve label set label or a language label, use PicklistService.getPicklist(com.veeva.vault.sdk.api.picklist.PicklistRequest) and PicklistService.getPicklistValueMetadataCollection(com.veeva.vault.sdk.api.picklist.PicklistValueMetadataCollectionRequest), specifying the language or the label set in the request (Refer to documentation in these methods for the fallback behavior).
• Inactive Values: PicklistValueMetadataCollectionRequest is defaulted to only returned active picklist values. PicklistValueMetadataCollectionRequest.Builder.withInactive() will need to be included in the request to retrieve inactive picklist values.
• Check for Nulls: When retrieving a picklist or picklist value, the result could be null. This is the case if the picklist or picklist value with the specified public key does not exist or was filtered out by the request criteria. Ensure to perform a null check to prevent NullPointerException.

Interfaces

Class	Description
Picklist	Provides methods to retrieve information about a picklist.
PicklistDependency	Provides methods to retrieve picklist dependency metadata.
PicklistDependencyMetadataCollectionRequest	Request to retrieve picklist dependency information.
PicklistDependencyMetadataCollectionRequest.Builder	Creates an instance of PicklistDependencyMetadataCollectionRequest.
PicklistDependencyMetadataCollectionResponse	Provides results from an executed PicklistDependencyMetadataCollectionRequest
PicklistRequest	Request to retrieve a Picklist object.
PicklistRequest.Builder	Creates an instance of PicklistRequest.
PicklistService	Service to retrieve picklist information.
PicklistValue	Provides access to picklist values, allowing retrieval of labels, status, name, and whether or not the value has dependencies.
PicklistValueMetadataCollectionRequest	Request to retrieve picklist value data.
PicklistValueMetadataCollectionRequest.Builder	Creates an instance of PicklistValueMetadataCollectionRequest.
PicklistValueMetadataCollectionResponse	Provides results from an executed PicklistValueMetadataCollectionRequest