Package com.veeva.vault.sdk.api.http

package com.veeva.vault.sdk.api.http
This package provides interfaces to make HTTP callouts to Vault or to an external service.

To make an HTTP callout, you must first set up a Connection in Vault Admin. Connections can be set up for the local Vault, with another Vault, or with an external application. Local and Vault to Vault connection types can be set up with an Authorized Connection User to control what data access is allowed. External connection types may also be set up to make request with basic authentication using username and password tokens. Learn more about HTTP Callout in the Developer Portal.

Supported Content-Types for all Vault-API and third-party callouts can be found at HttpRequestContentType.

The following is a simple example of a Vault-to-Vault callout: 

 
     //This is a vault to vault Http Request to the source connection
     //The configured connection provides the full DNS name.
     //For the path, you only need to append the API endpoint after the DNS.
     //The query endpoint takes a POST where the BODY is the query itself.
     HttpService httpService = ServiceLocator.locate(HttpService.class);
     FormHttpRequest request = httpService.newHttpRequestBuilder()
             .withConnectionName(connectionName)
             .withMethod(HttpMethod.POST)
             .withPath("/api/v24.2/query")
             .withHeader("Content-Type", "application/x-www-form-urlencoded")
             .withBodyParam("q", query.toString())
             .build();

     httpService.sendRequest(request, HttpResponseBodyValueType.JSONDATA)
             .onSuccess(httpResponse -> {

                 JsonData response = httpResponse.getResponseBody();

                 if (response.isValidJson()) {
                     String responseStatus = response.getJsonObject().getValue("responseStatus", JsonValueType.STRING);

                     if (responseStatus.equals("SUCCESS")) {

                         JsonArray data = response.getJsonObject().getValue("data", JsonValueType.ARRAY);
                         logService.info("HTTP Query Request: SUCCESS");

                         //Retrieve each record returned from the VQL query.
                         //Each element of the returned `data` JsonArray is a record with it's queried fields.
                         for (int i = 0; i < data.getSize();i++) {
                             JsonObject queryRecord = data.getValue(i, JsonValueType.OBJECT);
                             String sourceId = queryRecord.getValue("id", JsonValueType.STRING);
                             idList.add(sourceId);
                         }
                         data = null;
                     }
                     response = null;
                 }
                 else {
                     logService.info("getIntTransIds error: Received a non-JSON response.");
                 }
             })
             .onError(httpOperationError -> {
                 logService.info("getIntTransIds error: httpOperationError.");
             }).execute();

     request = null;
     return idList;
     
 }

Token Resolution

FormHttpRequest.Builder supports token resolution in the request's headers, body parameters, and body. Supported tokens include: In order for tokens to be resolved, .withResolveTokens must be set to true for the request.

Strongly typed values will be resolved into Strings for the request as described below:

  • String: resolved as-is.
  • Boolean: resolved with Boolean.toString(boolean)
  • BigDecimal: resolved with BigDecimal.toString()
  • LocalDate: resolved in the ISO-8601 format. For example, 2001-02-03.
  • ZonedDateTime: resolved in the ISO-8601 format. For example, 2001-02-03T04:05:06.007Z.
  • List<String>: resolved as a comma-separated list of values. Values that contain commas or line endings will be surrounded by double-quotes. For example, "Address, Street". Values that contain double-quotes or escapes will be escaped by pre-pending the character with \.

Authorization Tokens

HttpTokens provides tokens built-in to HttpService that you can use in a FormHttpRequest to pass authentication values to an external application.

The following example shows how to use Authorization tokens with a Basic Auth Connection Authorization type to authenticate using User Name and Password: 
 
      FormHttpRequest request = httpService.newHttpRequestBuilder()
                 .withConnectionName("external_callout")
                 .withMethod(HttpMethod.POST)
                 .withHeader("username", HttpTokens.AUTH_USER_NAME)
                 .withHeader("password", HttpTokens.AUTH_USER_PASSWORD)
                 .withResolveTokens(true)
                 .build();
This example shows how to use a Client Credential Connection Authorization type to authenticate using a Client ID and Client Secret: 

      FormHttpRequest request = httpService.newHttpRequestBuilder()
                 .withConnectionName("external_callout")
                 .withMethod(HttpMethod.POST)
                 .withHeader("client_id", HttpTokens.AUTH_CLIENT_ID)
                 .withHeader("client_secret", HttpTokens.AUTH_CLIENT_SECRET)
                 .withResolveTokens(true)
                 .build();

About Vault Tokens

All Vaults include system-provided tokens for Vault information: vault_id__sys, vault_name__sys, and vault_dns__sys. You can define and store up to ten (10) additional tokens using the Vaulttoken MDL component type.

A Vault token name is the name of the Vaulttoken record prefixed with "Vault", for example, ${Vault.api_version__c}. The following example shows an MDL command to create a Vault token that sets the API version to v22.2. You could create Vault tokens with the same name but different API versions in other Vaults. This would allow you to run the same code using different API versions in different Vaults. 

 
      RECREATE Vaulttoken api_version__c (
          label('22.2'),
          active(true),
          clone_behavior('clear__sys'),
          type('string__sys'),
          system_managed(),
          value('v22.2')
          );

The following is a simple example of creating a tokenized request: 

 
      HttpService httpService = ServiceLocator.locate(HttpService.class);
      TokenService tokenService = ServiceLocator.locate(TokenService.class);

      TokenRequest tokenRequest = tokenService.newTokenRequestBuilder()
                 .withValue("Custom.product_name", "CholeCap")
                 .withValue("Custom.status", "active__v")
                 .withValue("Custom.pagesize", new BigDecimal(10))
                 .build();

      FormHttpRequest request = httpService.newHttpRequestBuilder()
                 .withConnectionName("remote_vault_callout")
                 .withMethod(HttpMethod.POST)
                 .withPath("/api/${Vault.api_version__c}/query")
                 .withBodyParam("q", "select name__v from product__v where name__v = '${Custom.product_name}' and status__v = '${Custom.status}' PAGESIZE ${Custom.pagesize}")
                 .withTokenRequest(tokenRequest)
                 .withResolveTokens(true)
                 .build();