Upgrading to Grantor Web Service Library V2.0
The latest version of the Grants.gov Agency 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.
- New schemas were added with Release 15.2 for Forecast web services.
NOTE: S2S V0 and V1 endpoints were discontinued January 4, 2016. Please use or upgrade to the S2S V2.0 endpoint.
Resources for Upgrading to Version 2.0
For agencies that are upgrading to Agency Web Services Library V2.0:
- Review the About Web Service V2.0 section below for information about V2.0.
- Review the Agency S2S Version Matrix and the Agency Web Services.
- Download the Version 2.0 Agency WSDL using the link in the Agency Versions & WSDLs section.
- Download the Version 2.0 Web Service using the link found in the Agency Reference Implementation section.
About Web Service V2.0
All web services in the Web Service Library V2.0 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, but 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 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 that optional parameters be 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 in addition to the contents of each parameter. For example, 'ClosingDate' is an optional field in the UpdateAdobeOpportunity web service, and it should be set to null if you want to exclude this field from the web service call.
V2.0 required an upgrade 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 of 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:
AgencyWebServicesPortType port = service.getAgencyWebServicesSoapPort( new MTOMFeature(true) ); BindingProvider bp = ( BindingProvider ) port; bp.getRequestContext().put( JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192 );
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 Agency web services:
The following common schema standardize the naming convention. To use this common schema, set the GrantsCommonElements-V1.0 namespace declaration to 'xmlns:GrantsCommonElements'.
The following common schema standardize the definition of the common elements:
Agency Manage Package Schema
The following is the schema used by the Manage Package web service:
Agency Update Application Info Schema
The following is the Schema used by the Update Application Info web service:
Grants Forecast Synopsis Schema
The following is the Schema used by the Create Opportunity Forecast, Update Opportunity Forecast, and Delete Opportunity Forecast web services.
Grants Funding Synopsis Schema
The following is the Schema used by the Create Adobe Opportunity and Update Adobe Opportunity web services.
Grants Opportunity Schema
The following is the Schema used by the Create Opportunity Forecast, Create Opportunity Package, Get Forecast and Synopsis Details, Get Opportunity List, Get Package Details, and Get Related Document Details web services.
Grants Package Schema
The following is the Schema used by the Create Opportunity Package, Delete Opportunity Package, Update Opportunity Elements, and Update Opportunity Package web services.
Grants Related Document Schema
The following is the Schema used by the Get Related Document Details, Manage Related Document Files, Manage Related Document Folders, and Manage Related Document Links web services.