Agency Upgrading
Upgrading to Agency Web Service Library V2.0The 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.0For agencies that are upgrading to Agency Web Services Library V2.0: Change LogFrom Web Service Library V0 to V1The following web services were added to the Agency Web Service Library V1: - Manage Package
- Update Application Info
From Web Service Library V1 to V2.0VersioningIn 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 ServicesThe 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.
ValidationAll 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. MTOMV2.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 SchemasIn 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 SchemasThe 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 SchemaThe 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 SchemaThe 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 SchemaThe 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. |
|