Upgrading To Applicant Web Service Library V2.0

The latest version of the Grants.gov Applicant Web Service Library is Version 2.0 (V2.0). It consists of the following major enhancements:

  • Support for large submissions (up to 1.2 Gigabytes). Both single project and multi-project submissions now can be streamed to Grants.gov, greatly reducing size restrictions.
  • Enhanced validation using strongly typed objects in the WSDL. It is easier for users to validate their XML prior to invoking the web service.
  • New schemas were added to store common data elements to increase consistency in naming conventions.

Resources for Upgrading to Version 2.0

For applicants that are upgrading to Applicant Web Services Version 2.0:

Change Log

From Web Service Library V0 to V1

The following web services were added to the Applicant Web Service Library V1:

  • Authenticate AOR
  • Get Application Info
  • Get Opportunities' similar to the Get Opportunities With Info web service with the addition of the IsMultiProject flag to indicate if the package is single-project or multi-project
  • Submit Application as Third Party

The Submit Application web service was updated to include multi-project submissions.

The following are the changes to the Applicant WSDL:

  • The ApplicantIntegrationServices-V1.0 namespace declaration changed from xmlns:apis to xmlns:applicantws.
  • The OpportunityID and CompetitionID element definitions were changed from a string with a length between 1 and 100 (StringMin1Max100Type) to an uppercase alphanumeric value with a maximum length of 40 characters ([A-Z0-9\-]{1,40}).
  • The CFDANumber element definition changed from a string with a length between 1 and 15 (StringMin1Max15Type) to a numeric value with format "##.###" ([0'9]{2}[\.][0'9]{3}).
  • The Grants_govTrackingNumber element definition changed from a string with a length between 1 and 240 (StringMin1Max240Type) to a string with format "GRANT########" where "########" is an 8 digit number (GRANT[0-9]{8}).

From Web Service Library V1 to V2.0

Versioning

In V2.0, the concept of provisioning and versioning was introduced. Whenever an enhancement is required for the Interface, a new version of the Web Services Library will be created. A new WSDL will be generated and assigned the next logical version number.

<wsdl:service name="ApplicantWebServices-V2_0">
  <wsdl:port name="ApplicantWebServicesSoapPort" binding="applicantws:ApplicantWebServicesSoapBinding">
    <soap:address location="http://ws.grants.gov:446/grantsws-applicant/services/v2/ApplicantWebServicesSoapPort/" />
  </wsdl:port>
</wsdl:service> 


Web Services

The following changes were made to the web services:

  • The Get Opportunities with Info and the Get Opportunity List web services were deleted. All of their functionality is included in the Get Opportunities web service.
  • The Submit Application and Submit Application as Third Party web services were updated to support large submissions.

Validation

All V2.0 web services were changed to use strongly typed objects to allow the interfaces to become more descriptive in their input and output parameters. Clients are no longer passing an XML string; rather the client is populating the values in a value object and then dispatching it to the server in the input message. This change allows Grants.gov to perform an initial validation on the structure and the contents of each parameter upon invocation of the web service.

Using strongly typed objects and validation upon invocation requires optional parameters are set to null instead of an empty string. Empty tags can no longer be included in the XML for null fields. This validation checks the structure and the contents of each parameter. For example, CFDANumber is an optional field in the GetOpportunities web service and must be set to null to exclude this field from the web service call.

MTOM

V2.0 upgraded to the Message Transmission Optimization Mechanism (MTOM) in the application server for attachment streaming to support large submissions. This required a change in the signatures for the web services for receiving and sending attachments.

On the client side, the enabling of the MTOM feature is through setting properties when acquiring the service port. The code snippet below shows how the client can enable the MTOM feature:

ApplicantWebServicesPortType port = service.getApplicantWebServicesSoapPort( new MTOMFeature(true) );
               BindingProvider bp = ( BindingProvider ) port;
          bp.getRequestContext().put( JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192 );          

 

New External Schemas

In V2.0, the WSDL references external schemas act as a central repository for the different object types and elements used in each WSDL. This technique enables consistency of the various data structures used throughout the web service interfaces. The following are the active schemas for the Applicant web services:

The following common schema was added to standardize the naming convention:

To use this common schema, set the GrantsCommonElements-V1.0 namespace declaration to 'xmlns:GrantsCommonElements'. The following common schema was added to standardize the definition of the common elements: