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:

About Web Service V2.0

Validation

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.

MTOM

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 );

 

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 Agency web services:

Common Schemas

The following common schema standardize the naming convention. To use this common schema, set the GrantsCommonElements-V1.0 namespace declaration to 'xmlns:GrantsCommonElements'.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsCommonElements-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsCommonElements-V1.0.xsd

The following common schema standardize the definition of the common elements:

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsCommonTypes-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsCommonTypes-V1.0.xsd

Agency Manage Package Schema

The following is the schema used by the Manage Package web service:

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/AgencyManagePackage-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/AgencyManagePackage-V1.0.xsd

Agency Update Application Info Schema

The following is the Schema used by the Update Application Info web service:

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/AgencyUpdateApplicationInfo-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/AgencyUpdateApplicationInfo-V1.0.xsd

Grants Forecast Synopsis Schema

The following is the Schema used by the Create Opportunity Forecast, Update Opportunity Forecast, and Delete Opportunity Forecast web services.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsForecastSynopsis-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsForecastSynopsis-V1.0.xsd

Grants Funding Synopsis Schema

The following is the Schema used by the Create Adobe Opportunity and Update Adobe Opportunity web services.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsFundingSynopsis-V2.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsFundingSynopsis-V2.0.xsd

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.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsOpportunity-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsOpportunity-V1.0.xsd

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.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsPackage-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsPackage-V1.0.xsd

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.

Training Environment:
http://trainingapply.grants.gov/apply/system/schemas/GrantsRelatedDocument-V1.0.xsd

Production Environment:
http://apply07.grants.gov/apply/system/schemas/GrantsRelatedDocument-V1.0.xsd