19
© 2016 ConstructConnect. All rights reserved. 5/10/16 ConstructConnect Web Services Administrator’s Guide
© 2016 ConstructConnect. All rights reserved. 5/10/16
ConstructConnect Web Services
Administrator’s Guide
ConstructConnect Web Services Administrator’s Guide Page 2
Copyright notice and statement
© 2016 ConstructConnect. All rights reserved.
All rights reserved. No part of this document may be copied, photocopied, reproduced, or distributed in any form or by any means without permission in writing from ConstructConnect. Notice of liability Information in this document is subject to change without notice. Any software described in this document is furnished under a license agreement and may be used or copied only in accordance with the terms of the agreement.
ConstructConnect, 30 Technology Parkway South, Suite 100 Norcross, GA 30092
Document change record
The revision history follows in reverse chronological order.
Revision Date Change description
C May 2016 Rebranded for ConstructConnect.
B June 2015 Updated the URL for the enumeration values link in Appendix B – Enumeration values on page 19.
A April 2015 Original document
© ConstructConnect Web Services Administrator’s Guide Page 3
Table of Contents
Introduction .......................................................................................................................... 4
ConstructConnect Web Services overview ........................................................................... 5
Accessing the Insight database ....................................................................................................... 5 Protocol and framework methodology requirements ....................................................................... 5 Using the token key .......................................................................................................................... 5 Process flow description .................................................................................................................. 5
ConstructConnect Web Services method requests .............................................................. 6
Service method request element hierarchy ..................................................................................... 6 Service method request element descriptions ................................................................................. 7 Service request sort fields .............................................................................................................. 14
ConstructConnect Web Services method response ............................................................15
Service method response element hierarchy ................................................................................ 15 Service method response descriptions .......................................................................................... 16
Appendix A – Fields included in project search ...................................................................17
Appendix B – Enumeration values .......................................................................................19
ConstructConnect Web Services Administrator’s Guide Page 4
Introduction
The ConstructConnect Web Services lets customers create customized data extractions from the ConstructConnect database. These services query project, company and document data and return the response to the customer’s data interface.
About this document
This document is intended for use by technical personnel in the setup and implementation of the described services. Included are an introduction and description of the services, field description for both request and response values, and a visual representation of the services hierarchy.
Who should use this document
This document is intended for use by system administrators and other technical personnel in the implementation of ConstructConnect Web services. Contact your ConstructConnect representative if you have any questions about the content or use of this document.
© ConstructConnect Web Services Administrator’s Guide Page 5
ConstructConnect Web Services overview
Introduction
This section contains information about working with the services described in this document.
Accessing the Insight database
Use of this document assumes that you have the Insight production server URL and login credentials to access the Insight server database. If you do not have this information or have any questions about this requirement, contact your ConstructConnect representative.
Protocol and framework methodology requirements
The services described in this document assume familiarity with Simple Object Access protocol (SOAP) and Windows Communication Foundation (WCF) framework for requesting and receiving structured information in the implementation of web services in computer networks. If you have questions about this topic or any of the services described in this document, contact your system administrator.
Using the token key
A token key is required to access the ConstructConnect database. You must submit your credentials using the Login service method to receive your token key, and your token key must be included with each data service method request. Each of the data service method requests uses the same token key for validation.
Note: Your request is refused when your token key is expired or invalid. Resubmit your credentials to receive a new token key and replace the expired or invalid key before resubmitting your request.
Process flow description
The following describes the stages of the ConstructConnect Web Services request and response methods.
Stage Description
1 The client submits credentials using the Login service method.
2 The web services validates the credentials and returns the service request token key to the client.
3 The client adds the token key to the data service request and submits the request.
4 The web services validates the token key and processes the request.
5 The response to the data service request is returned to the client.
ConstructConnect Web Services Administrator’s Guide Page 6
ConstructConnect Web Services method requests
Introduction
There are four data service methods that can be used for the request:
GetProjectCompanies
GetProjectMaterialModels
GetProjectRoles
GetProjects
Note: The service method Login is only used to obtain the token key. For more information, see Using the token key on page 5.
Each data service method contains the same elements and uses the same token key. The unique response is determined by the parameters entered in the request.
Service method request element hierarchy
The following shows the element criteria hierarchy for the GetProjectRoles service method request:
© ConstructConnect Web Services Administrator’s Guide Page 7
Service method request element descriptions
This section contains a description of each of the service method request elements, including the name, description and data type for each element along with required formats and examples.
Element Data Type
Description Notes
CompanyDataSourceIDList String The country where the company is located, either United States or Canada.
Format: <company Id>|<COUNTRY>
Example:
1234567899|US
123456|CAN
CompanyGeographyList The country, state or province and county location of the company.
Format:
<tier>|<COUNTRY>|<Geo level 1>|<Geo level 2>
Example:
3|UNITEDSTATES|Georgia|Fulton
1|CANADA
2|UNITEDSTATES|Texas
CompanyIdList The ConstructConnect company identification number.
Can be from six to ten digits in length.
Example: 123456
CompanyKeywordTermList The company name. Example: Walmart, HOK
CompanyNoteList Terms in the company Personal Notes field. —
CompanyTypeList The role played by the company on at least one project.
Format: <tier>|<type>
Example:
1|ENGINEERS
2|ENGINEERS|Acoustical Engineer
DivisionIdList This value is not currently supported. —
ConstructConnect Web Services Administrator’s Guide Page 8
Element Data Type
Description Notes
DocumentTermList String Terms found in project plans and specifications.
Example: strut OR compression
Note: You can use Boolean terms for this request value. For more information about which terms are valid, contact your ConstructConnect sales representative.
IncludeNullValueProjects Boolean Determines if null value projects are included in the response.
Values:
False – Null value projects are not returned.
True – Null value projects are returned.
Default: False
PageNumber Integer Index of the page number to return, such as 1, 2, 3. This value works with PageSize to index a large volume of records in a response.
Notes:
The maximum page size in any request is 1000.
No results are returned when the request exceeds the number of results.
The total of all records matching the request is shown in the TotalRecords value for each response.
Example:
For a set of queries that can return several hundred records,
PageNumber=1 and PageSize=100 returns the first 100 records.
PageNumber=2 and PageSize=100 returns the second 100 of all records.
PageSize The number of records that are returned on each page. See the above for PageNumber for indexing the number of pages in a response.
© ConstructConnect Web Services Administrator’s Guide Page 9
Element Data Type
Description Notes
PlanList String Terms found specifically in project plans. Example: truss OR “steel girder”
Note: You can use Boolean terms for this request value. For more information about which terms are valid, contact your ConstructConnect sales representative.
ProjectBidTypeList Project bid types Values:
Invited bidders
Negotiated
Open bidding
Prequalified bidding
ProjectBiddingWithin Integer Days within which a project goes to bid. Default: Null
Note: You cannot use negative numbers.
Example: 30
ProjectCategoryIdList String The category and subcategories for the project.
Using the categories Civil or General includes all categories and subcategories.
You can use a combination of categories and subcategories: Civil, Athletic Buildings, Military.
Format: <tier>|<category>|<subcategory>
Example:
1|CIVIL
2|CIVIL|Airport
ConstructConnect Web Services Administrator’s Guide Page 10
Element Data Type
Description Notes
ProjectDataSourceIdList String The country where the project is located, either United States or Canada.
Format: <project Id>|<COUNTRY>
Example:
12345678|US
1234567899|CAN
ProjectGeographyList The country, state or province and county of the project.
Format:
<tier>|<COUNTRY|<Geo level 1>|<Geo level 2>
Example:
3|UNITED STATES|Georgia|Fulton
1|CANADA
2|UNITED STATES|Texas
ProjectIdList The seven to ten digit ConstructConnect identification code for the project.
Example:
121345678
2345678999
ProjectKeywordTermList Terms found on the project listing. Example:
work type
“invitation number” OR “bid rank”
Note: See Appendix A – Fields included in project search on page 17 for a full list of the terms in a project listing.
ProjectListedWithin Integer Days within which a project is listed. Starts at 1 (for 24 hours) to any number of days.
© ConstructConnect Web Services Administrator’s Guide Page 11
Element Data Type
Description Notes
ProjectMaterialDemandCSIList String The CSI / CSC codes for the anticipated materials for the project.
Format:
<tier>|<division>|<subdivision>
Example:
2|23|2300 (for HVAC)
2|23|2301 (for operation and maintenance of HVAC systems.)
Note: See the Construction Specification Institute website for more information on CSI / CSC codes.
ProjectMaterialIdList Currently not supported. —
ProjectMaxValue Long The maximum value range for a project. Use whole dollars only.
ProjectMinValue The minimum value range for a project.
ProjectNoteList String Terms found in the Personal Notes field of a project listing.
Example:
bidding
<assignee name>
ProjectOwnerTypeList String The type of the owner for a project. Values:
City
County
Federal
Private
State/Provincial
ConstructConnect Web Services Administrator’s Guide Page 12
Element Data Type
Description Notes
ProjectStageIdList String The stage of a project. Format: <tier>|<stage>|<substage>
Example:
1|BIDDING
2|BIDDING|SUBBIDS:ASAP
2|BIDDING|Biddate Set
Note: Unverified (or prospective) projects are included by default.
ProjectUpdatedWithin Integer Days since a project has been updated. Starts at 1 (for 24 hours) to any number of days.
ProjectVerificationStatus — The verification status of a project. Unverified projects are also known as prospective projects.
Values:
All – All entries are returned.
Unverified – Only unverified/prospective projects are returned.
Verified – Only verified projects are returned.
ProjectWorkTypeList String Project work types Values:
Addition
Addition/alteration
Alteration
New
ProjectZipCodeList The zip or postal code for the project. Example:
U.S. – 30033, 30033-0315
Canada – L0H 1GO
© ConstructConnect Web Services Administrator’s Guide Page 13
Element Data Type
Description Notes
ScopeList String Searches the text in the Scope, Notes and Details section of the project listing.
Note: You can use Boolean terms for this request value. For more information about which terms are valid, contact your ConstructConnect sales representative.
Example: “fit out” OR “retaining wall”
SortField — Fields that can be used to sort the response.
For more information, see Service request sort fields on page 14.
SortOrder The order in which the results are sorted according to the value selected in the SortField value, as described above.
Values:
ASC – Ascending order
DESC – Descending order
SpecList String Terms found in the specifications of project documents.
Example: truss OR “Andersen windows”
Note: You can use Boolean terms for this request value. For more information about which terms are valid, contact your ConstructConnect sales representative.
TitleList Terms found in the project titles. Example: “Aldi Food Store #9” OR “Walmart Express”
Note: You can use Boolean terms for this request value. For more information about which terms are valid, contact your ConstructConnect sales representative.
ConstructConnect Web Services Administrator’s Guide Page 14
Service request sort fields
The SortField element lets you select the value to use for sorting the response to the request.
The following lists the values you can use with the SortField element.
Sort field value Sort field value
ProjectId ProjectTitle
ProjectAddress ProjectCity
ProjectCounty ProjectStateProvince
ProjectZipPostalCode ProjectValuation
ProjectBidDate ProjectBidTime
ProjectUpdateDate ProjectListedDate
ProjectCategory ProjectSubCategory
ProjectStage ProjectSubStage
ProjectBidType ProjectOwnerType
ProjectWorkType ProjectMatchingDocuments
ProjectSelectedMaterialCost ProjectLEEDCertificationIntent
ProjectFloorArea ProjectNumofFloorsBelowGround
ProjectNumofFloors ProjectSiteArea
ProjectNumofStructures ProjectNumofUnits
CompanyName CompanyCountry
CompanyType RoleClassificationType
CompanyId CompanyPhoneNumber
CompanyFax CompanyEmail
CompanyMailingAddress CompanyMailingCity
CompanyMailingCounty CompanyMailingPostalCode
CompanyMailingStateProvince CompanyMailingCountry
CompanyAddress CompanyCity
CompanyCounty CompanyPostalCode
CompanyStateProvince CompanyLastUpdate
CompanyGeography CompanyListedDate
CompanyUpdateDate CompanyMainContact
CompanyWebsite CompanySelectedMaterialCost
CompanyTotalProjectValue ProjectPSA
ProjectPSAb ProjectSingleTradeClassificationType
ProjectMandatoryConferenceDate DocumentSnippet
GeoDistance —
© ConstructConnect Web Services Administrator’s Guide Page 15
ConstructConnect Web Services method response
Introduction
Each ConstructConnect web services response contains the same elements for each of the four request methods. The unique response is determined by the criteria selected for the request.
Service method response element hierarchy
The following example shows the response element hierarchy for the GetProjects request:
Note: The response elements are the same for each of the four request methods.
ConstructConnect Web Services Administrator’s Guide Page 16
Service method response descriptions
This section contains a description of the service method response elements.
Element Data type
Description Notes
RecordsReturned Integer The number of records returned for the specific page.
This response is determined by the PageSize value described on page 8.
Results <request name>
— The list of records for the designated page. —
TotalRecords Integer The total number of records in the Insight database that match the request.
—
Message — Information relating to the response. —
StatusCode Integer Indicates the status of the response. 0 = Success
99 = Failure
© ConstructConnect Web Services Administrator’s Guide Page 17
Appendix A – Fields included in project search
Introduction
This appendix contains a list of the project list fields that are included in a project search.
Note: The fields in this section are the keyword terms that relate to the ProjectKeywordTermList request element described on page 10.
The following table lists the fields on the project results page that are included in a project search, including the index status of each field.
Project field Indexed in project filter?
Project Name Yes
Address (Address Line 1, City, State, Zip Code)
County
Project ID
Value
Matching Docs No
Bid Date
Bid Time
Update Date
Single Trade Project Yes
List Date No
Stage Yes
Stage Comments 1
Stage Comments 2
Work Type
Owner Type
Contract Type
Invitation Number
Structures No
Floors Yes
Parent Project ID
LEED Certification Intent
Notes
Subbids
Contract Conditions
Details
Scope Yes
Company Role
ConstructConnect Web Services Administrator’s Guide Page 18
Project field Indexed in project filter?
Company Name
Contact Name
Address No
Phone
Fax
Email address
Company Name Yes
Added Date No
Address
Phone
Fax
Bidding Role
Bid Rank
Bid Value
Material Yes
Sub Material
Parent Classification No
Classification
Conditions
Bonding
Bid Date/Time
Bids To
Bid Type
Category Yes
Sub Category
© ConstructConnect Web Services Administrator’s Guide Page 19
Appendix B – Enumeration values
Introduction
This appendix contains a link to the enumeration values that you can use for the service method requests.
Enumeration values link
Click to download the Excel spreadsheet of Insight enumeration values.
