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.

Resources for Upgrading to Version 2.0

For agencies that are upgrading to Agency Web Services Library V2.0:

Change Log

From Web Service Library V0 to V1

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

  • Manage Package
  • Update Application Info

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="AgencyWebServices-V2.0">
  <wsdl:port name="AgencyWebServicesSoapPort"  binding="agencyws:AgencyWebServicesSoapBinding">
    <soap:address location="https://ws07.grants.gov:446/grantsws-agency/services/v2/AgencyWebServicesSoapPort"/>
  </wsdl:port>
</wsdl:service>

 

Web Services

The following changes were made to the web services:

  • The 'Save Opportunity' functionality was replaced with 'Create Opportunity' and 'Update Opportunity'. In addition to creating new opportunities and synopsis, the 'Create Opportunity' web service also allows the user to create a synopsis for opportunities created previously with only packages.
  • 'Manage Package' web service was updated to use the new 'AgencyManagePackage-V1.0' schema to allow agencies to submit large instruction files with their packages.
  • 'Update Application Info' was updated to use the new 'AgencyUpdateApplicationInfo-V1.0' schema.
  • 'Get Application' and 'Get Application Zip' web services were modified to provide the ability for agencies to download large submissions.

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

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

Common Schemas

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

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

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

To use this new 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:

Training Environment:
http://at07apply.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 new schema used by the Manage Package web service. This replaced the Web Service Library V1 string elements, ManagePackageRequestXML and ManagePackageResponseXML, with strongly typed objects:

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

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

The Web Service Library V2.0 AgencyManagePackage-V1.0.xsd schema has the following changes compared to the ManagePackageRequestXML and ManagePackageResponseXML elements in the Web Service Library V1 AgencyManagePackageXML-V1.0 schema:

  • The following elements were renamed for clarification and consistency:
Web Service Library V1 Element Name Web Service Library V2.0 Element Name
OpenToApplicantType OpenToApplicant
OpportunityTitle FundingOpportunityTitle
SendEmail SendChangeNotificationEmail
EmailComments ModificationComments
ErrorMsg ErrorDetails
ElectronicRequired ElectronicSignatureRequired
  • Added a new element type: OpportunityDateType
Agency Update Application Info Schema

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

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

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

Grants Funding Synopsis Schema

The following is the new Schema used by the Create Adobe Opportunity and Update Adobe Opportunity web services. This replaced the GrantsFundingSynopsis.dtd used in Web Service Library V1.

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

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

The GrantsFundingSynopsis-V2.0 schema has the following changes:

  • Uses the new common schemas
  • The GrantsFundingSynopsis-V2.0 namespace declaration is 'xmlns:GrantsFundingSynopsis'.
  • The following elements were renamed for clarification and consistency:
Web Service Library V1 Element Name Web Service Library V2.0 Element Name
PostDate PostingDate
FundingInstrumentType FundingInstrument
FundingOppTitle FundingOpportunityTitle
FundingOppNumber FundingOpportunityNumber
ApplicationsDueDate ClosingDate
ApplicationsDueDateExplanation ClosingDateExplanation
FundingOppDescription FundingOpportunityDescription
EligibilityCategory EligibleApplicantTypes
AdditionalEligibilityInfo OtherEligibleApplicantExplanation
ObtainFundingOppText AdditionalInformation
  • Added AgencyContactDescription as a sub-element of AgencyContact and changed AgencyEmailDescriptor to AgencyEmailDescription.
  • Removed the unused FederalAgencyName element.
  • Added 2 new elements: SendChangeNotificationEmail and ModificationComments.
  • The following table contains the validation changes:
Web Service Library V2.0 Element Name Web Service Library V1 Validation Web Service Library V2.0 Validation
PostingDate MMDDYYYY MM/DD/YYYY
UserID Any character Spaces and non-whitespace characters are allowed. (line feeds, carriage returns and tabs not allowed)
FundingInstrument No restriction Allowed values are 'CA/G/PC/O'
FundingActivityCategory No restriction Allowed values are 'RA/AG/AR/BC/CD/CP/DPR/ED/ELT/EN/ENV/FN/HL/HO/HU/IS/ISS/LJL/NR/O/RD/ST/T'
FundingOpportunityTitle Max Length is 250 Cannot start with whitespace character (line feeds, tabs, spaces, carriage returns), can be followed by any sequence of characters except new line, max length of 255.
FundingOpportunityNumber Max Length is 30 Valid characters: Numbers, Uppercase Letters and Hyphens. Max length is 40.
ClosingDate MMDDYYYY MM/DD/YYYY
ClosingDateExplanation Max Length is 250 Valid Characters: Any character. Max length is 4000 characters.
ArchiveDate MMDDYYYY MM/DD/YYYY
FundingOpportunityDescription Max Length is 18000 Valid Characters: Any character. Max length is 2500 characters.
CFDANumber No restriction ##.### (where # is a digit)
EligibleApplicantTypes No restriction Allowed values: '99/25/23/22/21/20/13/12/11/08/07/06/05/04/02/01/00'
OtherEligibleApplicantExplanation Max Length is 2500 Valid Characters: Any character. Max length is 4000 characters.
CostSharingOrMatchingRequirement No restriction Allowed values: 'Yes/No'
AgencyContact No restriction AgencyContactDescription (Sub element): Any character and Max length is 2500. AgencyEmailAddress (Sub element): Any character and Max length is 130. AgencyEmailDescription (Sub element): Any character and Max length is 102.