Skip to Content
Version 1.3 by Roelof Zwaan on 2021/11/22 10:43
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 To connect with the TerraIndex database to retreive projects from or upload new projects, you can connect to a webservice. This webservice provides Exports and enables these export with changes to be uploaded again.
6
7 There are two steps to consider, it’s possible to request an exact projectcode export or you could request all changed projects from a timestamp. This last option is an additional Webservice call that is very easy to use. It will tell you what Project to download because they have changes since a timestamp. This Timestamp could be your last donwload moment.
8 )))
9 )))
10
11 {{box title="**Contents**"}}
12 [[image:data:image/gif;base64,R0lGODlhAQABAPABAP///wAAACH5BAEKAAAALAAAAAABAAEAAAICRAEAOw==||height="15" role="presentation" title="Click and drag to move" width="15"]]
13 {{/box}}
14
15 (% class="row" %)
16 (((
17 (% class="col-xs-12 col-sm-8" %)
18 (((
19 == 1. Retreive all changed project from TerraIndex ==
20
21 To retreive all changed project from the TerraIndex database since a specific timestamp, there is a webservice call you can do. This will return all project rows that have changes since the timestamp you send within the request.
22 This way you only download projects that have changes, and it will not request project that are not needed, so it won’t keep our servers busy with exports that are not necessary.
23
24 To start connecting this webservice, you should use this URL:
25 [[https:~~/~~/web.terraindex.com/DataWS/ITWDataRestService_V1_0/GetProjectsJSON>>url:https://web.terraindex.com/DataWS/ITWDataRestService_V1_0/GetProjectsJSON]]
26
27 Fill the **Body **of a **POST **HTTP call with:
28
29 {{code language="JSON" layout="LINENUMBERS"}}
30 {
31 "Authorisation": {
32 "Username": "username",
33 "Password": "password",
34 "Licensenumber": 123,
35 "ApplicationCode": 12,
36 "Language": "en"
37 },
38 "LanguageCode": "en",
39 "WebserviceVersion": 1,
40 "SearchFilter": "",
41 "ArchiveID": 0,
42 "PageSize": 30,
43 "LastRowNR": 0,
44 "OrderPreviewBy": 2,
45 "FromDateContentLastChanged": "2019-04-01T00:00:00"
46 }
47 {{/code}}
48
49
50 Set the correct values for:
51
52 * (% class="mark" %)username(%%); as the username in TerraIndex
53 * (% class="mark" %)password(%%); as the username in TerraIndex
54 * (% class="mark" %)LicenseNumber(%%); as your companies license number
55 * (% class="mark" %)ApplicationCode(%%); as provided by TerraIndex to you, if not provided, request one at: service@terraindex.com
56 * (% class="mark" %)PageSize (%%)is in the example set to 30, it will return max 30 projects if possible. This can be upgraded to more records, but it will take longer.
57 * (% class="mark" %)FromDateContentLastChanged(%%); set the correct timestamp of your last call, it will return all projects that have been changed since that timestamp.
58 * (% class="mark" %)SearchFilter(%%); set a part of the projectcode in this field and it will search for projectcodes with this specific text part in it. It will add wildcars in front and at the end of the searchfilter automatically. So not needed to provide. The searchfilter will be applied on three columns: Project Code, Project Name and Project location City name.
59 * (% class="mark" %)LastRowNR(%%); fill default with zero/'0'. If your project isn’t in the first page of 30, you could use this field for lazy loading. Call the webservice with in the request the LastRowNR = 30, and you will receive project rows 31 t/m 60 (when the pagesize is 30).
60
61 Fill the header with:
62
63 {{code language="none"}}
64 application/json
65 {{/code}}
66
67
68 You will receive a reponse like this:
69
70 {{code language="JSON" layout="LINENUMBERS"}}
71 [
72 {
73 "PrID": 242,
74 "PrCode": "2018-010-DEMO",
75 "PrName": "TU Delft, the Netherlands",
76 "PrTypeCode": null,
77 "PrLocName": null,
78 "PrLocCity": null,
79 "PrLeaderCode": "Consult",
80 "PrConsultancyFirm": "TerraIndex",
81 "PrFieldworkFirm": "TerraIndex",
82 "PrPrincipalName": null,
83 "PrDateLastChanged": "2018-08-31T11:12:50.45",
84 "RowNumber": 1,
85 "Uitwissel": 0,
86 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
87 },
88 {
89 "PrID": 241,
90 "PrCode": "2018-009-DEMO",
91 "PrName": "TU Delft, the Netherlands",
92 "PrTypeCode": null,
93 "PrLocName": null,
94 "PrLocCity": null,
95 "PrLeaderCode": "Consult",
96 "PrConsultancyFirm": "TerraIndex",
97 "PrFieldworkFirm": "TerraIndex",
98 "PrPrincipalName": null,
99 "PrDateLastChanged": "2018-08-31T11:12:48.603",
100 "RowNumber": 2,
101 "Uitwissel": 0,
102 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
103 },
104 {
105 "PrID": 240,
106 "PrCode": "2018-008-DEMO",
107 "PrName": "TU Delft, the Netherlands",
108 "PrTypeCode": null,
109 "PrLocName": null,
110 "PrLocCity": null,
111 "PrLeaderCode": "Consult",
112 "PrConsultancyFirm": "TerraIndex",
113 "PrFieldworkFirm": "TerraIndex",
114 "PrPrincipalName": null,
115 "PrDateLastChanged": "2018-08-31T11:12:46.46",
116 "RowNumber": 3,
117 "Uitwissel": 0,
118 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
119 },
120 {
121 "PrID": 239,
122 "PrCode": "2018-007-DEMO",
123 "PrName": "TU Delft, the Netherlands",
124 "PrTypeCode": null,
125 "PrLocName": null,
126 "PrLocCity": null,
127 "PrLeaderCode": "Consult",
128 "PrConsultancyFirm": "TerraIndex",
129 "PrFieldworkFirm": "TerraIndex",
130 "PrPrincipalName": null,
131 "PrDateLastChanged": "2018-08-31T11:12:44.853",
132 "RowNumber": 4,
133 "Uitwissel": 0,
134 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
135 },
136 {
137 "PrID": 238,
138 "PrCode": "2018-006-DEMO",
139 "PrName": "TU Delft, the Netherlands",
140 "PrTypeCode": null,
141 "PrLocName": null,
142 "PrLocCity": null,
143 "PrLeaderCode": "Consult",
144 "PrConsultancyFirm": "TerraIndex",
145 "PrFieldworkFirm": "TerraIndex",
146 "PrPrincipalName": null,
147 "PrDateLastChanged": "2018-08-31T11:12:43.033",
148 "RowNumber": 5,
149 "Uitwissel": 0,
150 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
151 },
152 {
153 "PrID": 237,
154 "PrCode": "2018-005-DEMO",
155 "PrName": "TU Delft, the Netherlands",
156 "PrTypeCode": null,
157 "PrLocName": null,
158 "PrLocCity": null,
159 "PrLeaderCode": "Consult",
160 "PrConsultancyFirm": "TerraIndex",
161 "PrFieldworkFirm": "TerraIndex",
162 "PrPrincipalName": null,
163 "PrDateLastChanged": "2018-08-31T11:12:41.273",
164 "RowNumber": 6,
165 "Uitwissel": 0,
166 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
167 },
168 {
169 "PrID": 236,
170 "PrCode": "2018-004-DEMO",
171 "PrName": "TU Delft, the Netherlands",
172 "PrTypeCode": null,
173 "PrLocName": null,
174 "PrLocCity": null,
175 "PrLeaderCode": "Consult",
176 "PrConsultancyFirm": "TerraIndex",
177 "PrFieldworkFirm": "TerraIndex",
178 "PrPrincipalName": null,
179 "PrDateLastChanged": "2018-08-31T11:12:39.57",
180 "RowNumber": 7,
181 "Uitwissel": 0,
182 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
183 },
184 {
185 "PrID": 235,
186 "PrCode": "2018-003-DEMO",
187 "PrName": "TU Delft, the Netherlands",
188 "PrTypeCode": null,
189 "PrLocName": null,
190 "PrLocCity": null,
191 "PrLeaderCode": "Consult",
192 "PrConsultancyFirm": "TerraIndex",
193 "PrFieldworkFirm": "TerraIndex",
194 "PrPrincipalName": null,
195 "PrDateLastChanged": "2018-08-31T11:12:37.77",
196 "RowNumber": 8,
197 "Uitwissel": 0,
198 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
199 },
200 {
201 "PrID": 234,
202 "PrCode": "2018-002-DEMO",
203 "PrName": "TU Delft, the Netherlands",
204 "PrTypeCode": null,
205 "PrLocName": null,
206 "PrLocCity": null,
207 "PrLeaderCode": "Consult",
208 "PrConsultancyFirm": "TerraIndex",
209 "PrFieldworkFirm": "TerraIndex",
210 "PrPrincipalName": null,
211 "PrDateLastChanged": "2018-08-31T11:12:36.02",
212 "RowNumber": 9,
213 "Uitwissel": 0,
214 "geometryWKT_WGS84": "POINT (6.1000890695634133 52.58846240818189)"
215 },
216 {
217 "PrID": 233,
218 "PrCode": "2018-001-DEMO",
219 "PrName": "TU Delft, the Netherlands",
220 "PrTypeCode": null,
221 "PrLocName": null,
222 "PrLocCity": null,
223 "PrLeaderCode": "Consult",
224 "PrConsultancyFirm": "TerraIndex",
225 "PrFieldworkFirm": "TerraIndex",
226 "PrPrincipalName": null,
227 "PrDateLastChanged": "2018-08-31T11:12:30.037",
228 "RowNumber": 10,
229 "Uitwissel": 0,
230 "geometryWKT_WGS84": "POINT (4.3694882989839243 52.00722295311251)"
231 }
232 ]
233 {{/code}}
234
235 The **PrID **can be used as **ProjectID **in the next call to get the actual project xml file export.
236
237
238 == 2. Retreive the project export from TerraIndex ==
239
240 To request the export from TerraIndex we have a SOAP webservice. This webservice is called the ExportService, and it will provide a full project in TerraIndex Format.
241 The format of the projectfile is documentated here: [[Documentation TerraIndex Export format - dsFieldProject.xsd>>Implementatie dcoumentatie.Documentation TerraIndex Export format - dsFieldProject\.xsd.WebHome]]
242
243 To start connecting this webservice, you should use this URL of the Import Export Webservice:
244 [[https:~~/~~/web.terraindex.com/DataWS/ITWImportExportServiceASMX_V1_0.asmx>>url:https://web.terraindex.com/DataWS/ITWImportExportServiceASMX_V1_0.asmx]]
245
246 With this URL many IDE’s can create a proxy for you, just by providing the URL. Once this proxy is created, you will have a few classes looking like the call in the image below.
247
248 [[image:image-20200108-123431.png]]
249
250 The image is created with WebserviceStudio to visualise the SOAP call to send to the webservice.
251 This is the explanation of each number inside the image~:
252 1; The endpoint URL
253 2; Create the proxy based on the WSDL
254 3; Select the export call to see what it looks like
255 4; Fill the username + password of the TerraIndex user* to call the webservice with.
256 Also fill the license and the applicationCode. //(These two fields can be requested at the TerraIndex Servicedesk.)//
257 5; Fill the **ExportType **'**Export_FIELD_XML_v1_0_0**’. This export corresponds with dsFieldProject.xsd and is the best XML to connect TI with.
258 Create at least create 2 parameters as in the image. Beacause 2 parameters are needed.
259 6; Fill the parameter with the FileName.
260 7; Fill the parameter with **projectID**. Instead of ‘ProjectID' it’s also possible to fill the parameter ‘ProjectCode'.
261 8; Send the request and wait for the reponse. In response field ‘ResultCode’ should be 'SUCCES’ when it all went OK. If not it will tell what went wrong.
262 9; The response field 'Filecontent’is filled if it went OK, and it contains XML you can serialize.
263 \\*Username and password are known by each TI user and the application manager of your company can create new usernames.
264
265 **EXAMPLE CODE**
266
267 ExportType:
268 ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.ExportType.Export_Field_XML_v1_0_0;
269
270 {{code language="C#" layout="LINENUMBERS"}}
271 [TestMethod] public void Export_FieldXml_Local() {
272 ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.TWImportExportServiceASMX_V1_0SoapClient client = new ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.TWImportExportServiceASMX_V1_0SoapClient();
273 ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.ExportRequest req = new ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.ExportRequest() {
274 AuthorisationRequest = new ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.AuthorisationRequest() {
275 Username = "xxxxx", Password = "xxxxx", Licensenumber = "x"
276 }, LanguageCode = "eng", WebserviceVersion = "1.0",
277 };
278 req.TypeOfExport = ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.ExportType.Export_Field_XML_v1_0_0;
279 req.UseZipStream = true;
280 List < ExportParameter > paramsList = new List < ExportParameter > ();
281 paramsList.Add(new ExportParameter() {
282 ParameterType = ExportParameterType.FileName, StringValue = "Export"
283 });
284 paramsList.Add(new ExportParameter() {
285 ParameterType = ExportParameterType.ProjectID, FloatValue = 917
286 });
287 req.Parameters = paramsList;
288 try {
289 var result = client.Export(req);
290 if (result != null) {
291 if (result.ResultCode == ITWorks.TerraIndex.ImportExportTest.ImportExportServiceTest.ExportResultCode.Export_Succes) {
292 System.IO.File.WriteAllText(@ "C:\Temp\ExportTestField.xml", result.Files[0].FileContent);
293 System.IO.File.WriteAllText(@ "C:\Temp\ExportTestField.html", result.ExportLog);
294 } else {
295 throw new Exception(result.ResultCode.ToString() + " - " + result.ResultMessage);
296 }
297 }
298 } catch (Exception e) {
299 throw e;
300 }
301 }
302 {{/code}}
303
304 Example call
305
306 <soapenv:Envelope xmlns:soapenv="http:~/~/schemas.xmlsoap.org/soap/envelope/" xmlns:itw="https:~/~/wsterraindex.terraindex.com/ITWorks.TerraIndex/"> <soapenv:Header/> <soapenv:Body> <itw:Export> <itw:request> <itw:AuthorisationRequest> <itw:Username>USERNAME</itw:Username> <itw:Password>PASSWORD</itw:Password> <itw:Licensenumber>LICENSE</itw:Licensenumber> <itw:ApplicationCode>APPCODE</itw:ApplicationCode> </itw:AuthorisationRequest> <itw:WebserviceVersion>1.0</itw:WebserviceVersion> <itw:LanguageCode>nld</itw:LanguageCode> <itw:UseCompression>true</itw:UseCompression> <itw:TypeOfExport>Export_FIELD_XML_v1_0_0</itw:TypeOfExport> <itw:Parameters> <itw:ExportParameter> <itw:ParameterType>FileName</itw:ParameterType> <itw:StringValue>Export</itw:StringValue> </itw:ExportParameter> <itw:ExportParameter> <itw:ParameterType>projectID</itw:ParameterType> <itw:FloatValue>917</itw:FloatValue> </itw:ExportParameter> ~-~-~-~-- <itw:ExportParameter> <itw:ParameterType>ProjectCode</itw:ParameterType> <itw:StringValue>202020</itw:StringValue> </itw:ExportParameter> ~-~-~-~- </itw:Parameters> <itw:LogFormat>XML</itw:LogFormat> <itw:UseZipStream>true</itw:UseZipStream> </itw:request> </itw:Export> </soapenv:Body></soapenv:Envelope>
307
308 Example response:
309
310 <soap:Envelope xmlns:soap="http:~/~/schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http:~/~/www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http:~/~/www.w3.org/2001/XMLSchema"> <soap:Body> <ExportResponse xmlns="https:~/~/wsterraindex.terraindex.com/ITWorks.TerraIndex/"> <ExportResult> <ResultCode>Export_Succes</ResultCode> <TypeOfExport>Export_TI_v1_0_0</TypeOfExport> <Files> <File> <FileName>917.xml</FileName> <TypeOfFile>Field_XML_Compressed</TypeOfFile> <FileContent>H4sIAAAAAAAEAFWRuZaqQABEP4hAGnAGggm6odlREFkkA2WRRRCBxv76YeYF70yFVXUqqBvgl4KQBzcZ8Aho2iqxdhxDSPDmNGjz9Z/weMa8/aimTAUeF42KgxRRzd3YaGfdXtvECEBvWafSNwf+dOsjVXpZUzs+lw/p3gBhuXQ5S8T3MdIBlxUQEam+LOVgVo4D8w4c2E8pEgp3haewcpQx1KQ41Z8DKWv16seaDLp3GABLuIKXK5Ucq31EfSXm0172YvG87hcbayYGdB1t0CbcuueLpU5UawgHSitFr564Aet5LeegD0/tocZDTvuIuc9Ja0tDFt/m7kZnomdVJc+2SkqBGXmTdPiiPzJa2OznLkX67p2PCNM7iHU11QbIilVkMDBVd0J8gK4Ams6ycJQagnww/SaxuiZ/EdS6DZ0cf17BIhUq87CSkQvxat/2dEG1xu94BoaeT7C8XR38/C1DZbpygwfW+gk8Z+Mgm3DDhAj8r6099Rj+5YNs5F3+5R5EUPmd6+EvYvj1Dd8o9lLwAQAA</FileContent> </File> <File> <FileName>ProjectInfo.xml</FileName> <TypeOfFile>Field_XML_Compressed</TypeOfFile> <FileContent>H4sIAAAAAAAEAI1Qy5JDQAD8IAdj1/M4hJggDBnEbTxDsV7BxtdvNqm9bx+6urq7+tBEnw+qiuETCLrcTlst9Pajtb0soj7JeynztNIubHK9XZJOXoojN8dXpaxltOlOwAZzK033Edx7HWT1ZFVYNljpsT7iCVDbxb5tlmw3GhV7vgty5jqiGzWSYEvL7RCIQifzchIoMJnHz+fO17C4JAwA0hNRb247SR1ba8OunCV4ralK1rjwBhUAJ2pihopeuxqXIUecePETLhx8zT6IZX5GzafC0XHTrauISeyIM2+2g1PzEymRZrTtglKlsFYHXDKmoYTp+jw1zNDyAFZOTN9XHkuNGmU33905uipWMTsjm2ccm6+bxqk2xAjCf/z3BwS1j+qVqTjrlDGJziCIhC59CHwafeNgI8d3U4cQQ+VXSdXb+QGLuAuvrAEAAA==</FileContent> </File> </Files> </ExportResult> </ExportResponse> </soap:Body></soap:Envelope>
311
312
313 == Zip Stream class ==
314
315 If needed, this is the Zip Stream class you can use to extract the zipstream as used above:
316
317 ~/~// <summary> ~/~// Helper class for compress en decompress of file data ~/~// </summary> public static class ZipStreamHelper { #region Compress and encode ~/~// <summary> ~/~// Comprimeer een string en geeft deze terug in Base64 string. ~/~// </summary> ~/~// <param name="content">filecontent</param> ~/~// <returns>gecomprimeerde string</returns> public static string CompressToBase64String(string content) { ~/~/string to byte[] byte[] contentArray = stringToByteArray(content); ~/~/ Compress byte[] compressed = Compress(contentArray); return base64_encode(compressed); } ~/~// <summary> ~/~// Zet een string om naar een ByteArray ~/~// </summary> ~/~// <param name="content">filecontent</param> ~/~// <returns>ByteArray</returns> public static byte[] stringToByteArray(string content) { System.Text.UTF8Encoding encoding = new System.Text.UTF8Encoding(); return encoding.GetBytes(content); } ~/~// <summary> ~/~// comprimeer een ByteArray ~/~// </summary> ~/~// <param name="data">filedata als ByteArray</param> ~/~// <returns>gecomprimeerde ByteArray</returns> public static byte[] Compress(byte[] data) { using (var compressedStream = new MemoryStream()) using (var zipStream = new GZipStream(compressedStream, CompressionMode.Compress)) { zipStream.Write(data, 0, data.Length); zipStream.Close(); return compressedStream.ToArray(); } } ~/~// <summary> ~/~// Zet een ByteArray om naar een Base64 string ~/~// </summary> ~/~// <param name="data">gecomprimeerde ByteArray</param> ~/~// <returns>Base 64 string</returns> public static string base64_encode(byte[] data) { if (data == null) return string.Empty; return Convert.ToBase64String(data); } ~/~// <summary> ~/~// Zet een string om naar een Base64 string ~/~// </summary> ~/~// <param name="data">string</param> ~/~// <returns>Base 64 string</returns> public static string string_base64_encode(string data) { if (string.IsNullOrEmpty(data)) return string.Empty; ~/~/string to byte[] byte[] contentArray = stringToByteArray(data); return base64_encode(contentArray); } #endregion #region Decompress and decode ~/~/ Decode and decompress ~/~// <summary> ~/~// Decomprimeer een Base64 string naar een string ~/~// </summary> ~/~// <param name="contentBase64">GZIP Base64 string</param> ~/~// <returns>string</returns> public static string DecompressBase64StringToString(string contentBase64) { ~/~/ Decompress byte[] decoded = base64_decode(contentBase64); byte[] decompressed = Decompress(decoded); return byteArrayTostring(decompressed); } ~/~// <summary> ~/~// Zet een ByteArray om in een normale string ~/~// </summary> ~/~// <param name="data">ByteArray</param> ~/~// <returns>string</returns> public static string byteArrayTostring(byte[] data) { System.Text.UTF8Encoding enc = new System.Text.UTF8Encoding(); return enc.GetString(data); } ~/~// <summary> ~/~// Zet een Base64 string om naar een ByteArray ~/~// </summary> ~/~// <param name="encodedData">Base64 string</param> ~/~// <returns>gecomprimeerde ByteArray</returns> public static byte[] base64_decode(string encodedData) { byte[] encodedDataAsBytes = Convert.FromBase64String(encodedData); return encodedDataAsBytes; } ~/~// <summary> ~/~// Zet een gecomprimeerde ByteArray om in een ByteArray ~/~// </summary> ~/~// <param name="data">gecomprimeerde ByteArray</param> ~/~// <returns>ByteArray (gedecomprimeerd)</returns> public static byte[] Decompress(byte[] data) { using (var compressedStream = new MemoryStream(data)) using (var zipStream = new GZipStream(compressedStream, CompressionMode.Decompress)) using (var resultStream = new MemoryStream()) { var buffer = new byte[4096]; int read; while ((read = zipStream.Read(buffer, 0, buffer.Length)) > 0) { resultStream.Write(buffer, 0, read); } return resultStream.ToArray(); } } #endregion }
318 )))
319
320
321 (% class="col-xs-12 col-sm-4" %)
322 (((
323
324 )))
325 )))