Skip to Content

Setting up Lab communication by REST services with TerraIndex

Version 2.1 by Robin Huisman on 2022/02/08 11:48

Firewall IP-Adresssen van TerraIndex

Onze IP-adressen:

ingaand Web.terraindex.com
137.116.199.164

ingaand Test.terraindex.com
104.45.9.128

Productie uitgaand
40.115.34.64

Test uitgaand
13.73.138.173

CD/CI uitgaand
40.114.238.16

Kantoor VPN uitgaand  (niet meer in gebruik, was de oude OpenVPN)
10.33.66.215

Kantoor uitgaand
213.124.115.132

Oude Citrix uitgaand (citrix is ook verhuisd, dit is niet meer in gebruik)
83.96.194.140

Labaanlever bestanden uitwisseling

Oplossing/Design

ActionTerraIndex LaboratoriumParameters/MessageRemarksResultCodes
1Sends a request to the function: GetCustomers().> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string)		  
2  Receives the request and check the customers this username and searches the dateLastChanged for this Customer.   
3 <=Sends back the list of customers with the lastChangedTimestampResultCode (),
ErrorMessage (string),
List<customer> , Customer:
CustomerCode (string),
CustomerName (string),
LabID (int),
LabName (string),
ChangedTimeStamp (DateTime)		We receive the dateTimestamp instead of sending it, so we always get the full list and we are also able to delete customercodes.1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
4Receives the list of Customers, and will check for each customer it needs to request a new/changed labdelivery file based on the ChangedTimestamp.   If a customer is not longer in this list, TerraIndex can remove this customercode from the customer database. 
5Sends a request to the function: GetProductList() if it has changed.> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string),
LabID (int),
CustomerCode (string),
LanguageCode (string, default 'nld' volgens ISO 639-3-codes),
SIKBVersion (string, default: '13.4.0'),
UseZipStream/UseZip (bool, default: 'false')

We start with dutch, then extend with multiple languages, TerraIndex is in the lead to request multiple languages.
TerraIndex uses: 'fra', 'nld', 'eng', 'spa', 'deu', 'ita', 'por', 'dan'

Besides SIKB 13.4.0, TerraIndex also supports 9.0.0/8.0.0 etc.

 
6  Reveives a request to create a labdelivery file in a certain version of SIKB. It will generate the file.   
7 <=Sends back the SIKB file, as a Base64 encoded string, with or without using a zipstream.ResultCode (),
ErrorMessage (string),
FileContent_Base64 (string),
UseZipStream/UseZip (bool, default: 'false')		 1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
8Receives the DeliveryFile and saves the file for import into customer database.     
9Go back to step 5, for every Customer code, every language.     
10Process the LabDeliveryFiles     

Get Customers (POST)

Request example

public GetCustomersCall.Response GetCustomers(string WebserviceUsername, string WebservicePassword, string CustomerUsername)
        {
            GetCustomersCall.Response set = new GetCustomersCall.Response();

            try
            {
                var content = new FormUrlEncodedContent(new[]
                {
                    new KeyValuePair<string, string>("userName", WebserviceUsername),
                    new KeyValuePair<string, string>("password", WebservicePassword),
                    new KeyValuePair<string, string>("customerUsername", CustomerUsername),
                });

                HttpResponseMessage response = _HttpClient.PostAsync(_HttpClient.BaseAddress + "/GetCustomers", content).Result;
                response.EnsureSuccessStatusCode();
                string responseMessage = response.Content.ReadAsStringAsync().Result;

                if (string.IsNullOrEmpty(responseMessage))
                {
                    throw new Exception("Empty response from: [" + _HttpClient.BaseAddress + " / GetCustomers" + "]");
                }
                using (var ms = new System.IO.MemoryStream(System.Text.Encoding.UTF8.GetBytes(responseMessage)))
                {
                    XmlSerializer serializer = new XmlSerializer(typeof(GetCustomersCall.Response));
                    set = (GetCustomersCall.Response)serializer.Deserialize(ms);                 
                }
            }
            catch (Exception ex)
            {
                #region handle exception
                set.Status = new BusinessEntities.LabRestService.GetCustomersCall.ResponseStatus();
                set.Status.StatusCode = ((int)ResultCodes.GeneralError).ToString();               
                set.Status.ErrorMessage = "Exception occurred in GetCustomers (username: " + WebserviceUsername + ", password: " + WebservicePassword + ") with message: " + ex.Message;
                ex.Data.Add("WebserviceUsername", WebserviceUsername);
                ex.Data.Add("WebservicePassword", WebservicePassword);
                ex.Data.Add("CustomerUsername", CustomerUsername);
                ExceptionHandler.HandleException(ex);
                #endregion
            }
            return set;
        }

 

POST https://<URL>/GetCustomers HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Host: 81.175.89.24

Content-Length: 115

Expect: 100-continue

userName=<webservice_username>&password=<Webservice_password>&customerUsername=<customer_username or token>

Response example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<Response><Customers>

  <Customer LabId="1" LabName="Example Laboratorium" CustomerId="300" CustomerName="Adviesbureau De bodemkoning - Rotterdam" LastModifiedOnClient="2019-05-08T11:05:14.17+02:00" />

  <Customer LabId="1" LabName="Example Laboratorium" CustomerId="656" CustomerName="Adviesbureau De bodemkoning - Delft" LastModifiedOnClient="2019-04-19T13:20:10.123+02:00" />

</Customers>

<Status>

    <StatusCode>1</StatusCode>

    <StatusCodeDescription>OK</StatusCodeDescription>

    <ErrorMessage></ErrorMessage>

</Status>

</Response>

Get Products (POST)

Request example

public GetProductsCall.Response GetProductList(string WebserviceUsername, string WebservicePassword, string CustomerUsername, string customerid, int labid, string sikbVersion, string languageCode)

        {

            GetProductsCall.Response set = new GetProductsCall.Response();

            try

            {

                bool useZipstream = true;

                var content = new FormUrlEncodedContent(new[]

                {

                    new KeyValuePair<string, string>("userName", WebserviceUsername),

                    new KeyValuePair<string, string>("password", WebservicePassword),

                    new KeyValuePair<string, string>("customerUsername", CustomerUsername),

                    new KeyValuePair<string, string>("languageCode", languageCode),

                    new KeyValuePair<string, string>("clientId", customerid),

                    new KeyValuePair<string, string>("sikbVersion", sikbVersion),

                    new KeyValuePair<string, string>("useZip", useZipstream.ToString() ),

                });

                HttpResponseMessage response = _HttpClient.PostAsync(_HttpClient.BaseAddress + "/GetProducts", content).Result;

                response.EnsureSuccessStatusCode();

                string responseMessage = response.Content.ReadAsStringAsync().Result;

                if (string.IsNullOrEmpty(responseMessage))

                {

                    throw new Exception("Empty response from: [" + _HttpClient.BaseAddress + " /GetProducts" + "]");

                }

                using (var ms = new System.IO.MemoryStream(System.Text.Encoding.UTF8.GetBytes(responseMessage)))

                {

                    XmlSerializer serializer = new XmlSerializer(typeof(GetProductsCall.Response));

                    set = (GetProductsCall.Response)serializer.Deserialize(ms);

                }

                if (useZipstream && !string.IsNullOrEmpty(set.FileContent))

                {

                    //convert from base64 string back to normal

                    //first check for real Base64, by checking there is no 'xml'  in it

                    if (!set.FileContent.Contains("<labaanlevering"))

                    {

                        set.FileContent = ZipStreamHelper.DecompressBase64StringToString(set.FileContent);

                    }

                }

            }

            catch (Exception ex)

            {

                #region handle exception

                set.Status = new BusinessEntities.LabRestService.GetProductsCall.ResponseStatus();

                set.Status.StatusCode = ((int)ResultCodes.GeneralError).ToString();

                set.Status.ErrorMessage = "Exception occurred in GetProducts (username: " + WebserviceUsername + ", password: " + WebservicePassword + ") with message: " + ex.Message;

                ex.Data.Add("WebserviceUsername", WebserviceUsername);

                ex.Data.Add("WebservicePassword", WebservicePassword);

                ex.Data.Add("CustomerUsername", CustomerUsername);

                ex.Data.Add("sikbVersion", sikbVersion);

                ex.Data.Add("customerid", customerid);

                ex.Data.Add("languageCode", languageCode);

                ExceptionHandler.HandleException(ex);

                #endregion

            }

            return set;

        }

POST https://<URL>/GetProducts HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Host: 81.175.89.24

Content-Length: 179

Expect: 100-continue

userName=<webservice_username>&password=<Webservice_password>&customerUsername=<customer_username or token>&languageCode=nld&clientId=300&sikbVersion=13.5.0&useZip=True

Response example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<Response>

<FileContent> {SIKB FILE in ZIPSTREAM BASE64 format}</FileContent>

<Status>

<StatusCode>1</StatusCode>

<StatusCodeDescription>OK</StatusCodeDescription>

<ErrorMessage></ErrorMessage>

</Status></Response>

Gebruikersaccount controleren.

Oplossing/Design

Bij iedere call gaan we geen username van de klanten meer sturen met een vast webservice username en password voor TerraIndex. Hier willen we ook snel op kunnen controleren of deze wel bestaat.

WebserviceUsername (string),
WebservicePassword (string),
CustomerUsername (string)

Hiervoor maken we een Webserice voor ValidCredentials Check: 

ActionTerraIndex LaboratoriumParameters/MessageRemarksResultCodes
1Sends a request to the function: ValidCredentials().> WebserviceUsername (string),
WebservicePassword (string),
CustomerUsername (string)		We want to skip the Password of the customer, and we use the WebserviceUsername + WebservicePassword for real authentication. 
2  Receives the request and checks the combination of WebserviceUsername and WebservicePassword is Ok. Then checks the CustomerUsername is valid.   
3 <=Sends back a Success of InvalidCredentialsResultCode (),
ErrorMessage (string),		 1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable

Check ValidCredentials (POST)

Request example

public ValidCredentialsCall.Response ValidCredentials(string WebserviceUsername, string WebservicePassword, string CustomerUsername, string customerid)

        {

            ValidCredentialsCall.Response set = new ValidCredentialsCall.Response();

            try

            {

                var content = new FormUrlEncodedContent(new[]

                {

                    new KeyValuePair<string, string>("userName", WebserviceUsername),

                    new KeyValuePair<string, string>("password", WebservicePassword),

                    //new KeyValuePair<string, string>("clientId", customerid),   // Optional

                    new KeyValuePair<string, string>("customerUsername", CustomerUsername),

                });

                HttpResponseMessage response = _HttpClient.PostAsync(_HttpClient.BaseAddress + "/ValidCredentials", content).Result;

                response.EnsureSuccessStatusCode();

                string responseMessage = response.Content.ReadAsStringAsync().Result;

                if (string.IsNullOrEmpty(responseMessage))

                {

                    throw new Exception("Empty response from: [" + _HttpClient.BaseAddress + " / ValidCredentials" + "]");

                }

                using (var ms = new System.IO.MemoryStream(System.Text.Encoding.UTF8.GetBytes(responseMessage)))

                {

                    XmlSerializer serializer = new XmlSerializer(typeof(ValidCredentialsCall.Response));

                    set = (ValidCredentialsCall.Response)serializer.Deserialize(ms);

                    return set;

                }

            }

            catch (Exception ex)

            {

                #region handle exception

                set.Status = new BusinessEntities.LabRestService.ValidCredentialsCall.ResponseStatus();

                set.Status.StatusCode = ((int)ResultCodes.GeneralError).ToString();

                set.Status.ErrorMessage = "Exception occurred in GetValidCredentials (username: " + WebserviceUsername + ", with message: " + ex.Message;

                ex.Data.Add("WebserviceUsername", WebserviceUsername);

                ex.Data.Add("WebservicePassword", WebservicePassword);

                ex.Data.Add("CustomerUsername", CustomerUsername);

                ExceptionHandler.HandleException(ex);

                #endregion

            }

            return set;

        }

POST https://<URL>/ValidCredentials HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Host: 81.175.89.24

Content-Length: 125

Expect: 100-continue

userName=<webservice_username>&password=<Webservice_password>&clientId=<optional otherwise empty>&customerUsername=<customer_username or token>

Response example

<?xml version="1.0" encoding="UTF-8" standalone="no"?><Response>

<Status>

<StatusCode>1</StatusCode>

<StatusCodeDescription>OK</StatusCodeDescription>

<ErrorMessage></ErrorMessage>

</Status>

</Response>

Opdrachten versturen (POST)

Oplossing/Design

Hiervoor maken we een Webserice voor CreateOrder om de opdracht aan te maken.
Na de create willen we in de toekomst een overzicht van het laboratorium in bijv. PDF tonen, waarbij de gebruiker de prijzen ziet en kan bevestigen of annuleren.
Afhankelijk van de keuze van de gebruiker bij het laboratorium, roept TerraIndex de ApproveOrder of de CancelOrder aan.

Voor nu gaan we er vanuit dat wij dit niet kunnen, en stuurt TerraIndex needsApprovalIsSupported = false mee. Mocht dit True worden in de toekomst, dan kan het Lab bij het result aangeven of het wel of niet nodig is, in het NeedsApprove veld.

ActionTerraIndex LaboratoriumParameters/MessageRemarksResultCodes
1Sends a request to the function: CreateOrder().> WebserviceUsername (string),
WebservicePassword (string),
CustomerUsername (string),
FileContent_Base64 (string),
UseZipStream/UseZip (bool, default: 'false'),
CustomerCode (string),
SIKBVersion (string, default: '13.4.0'),
needsApprovalIsSupported (bool)		SIKB Version included, so labs can quickly check the version.
Besides SIKB 13.4.0, TerraIndex also supports 9.0.0.

Before sending the SIKB, validate to the XSD!
And to the XSLT?

needsApprovalIsSupported = false; means we dont get PDF with offerte. This will make is faster.
needsApprovalIsSupported = true; means lab will check the user setting to send a PDF Offerte back or not. (If the lab can support this.)		 
2  Receives the request and checks the credentials.   
3  Credentials are valid, the Filecontent is checked on a valid Labassignment. When valid it will be processed and a OrderId is given. Laboratorium saves the Sample GUIDs if it's SIKB 13 or higher.
Otherwise we use the idanlmons unique ID.		 
   Based on what customer, the order will be approved or the approve needs to be done in laboratorium system.   
4 <=Sends back a Success with the new OrderIdResultCode (),
ErrorMessage (string),
OrderId (string),
NeedsApprove (bool),
FileContent_Base64 (string),
UseZipStream/UseZip (bool, default: 'false'),		In the future labs will send back the PDF with the prices and some checks. To approve or cancel. For the first version this is not required yet and the fileContent remains empty.1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
6Receives the OrderId, and saves it.
 		   

Default for now laboratorium will send:
NeedsApprove = False,
PDF = Empty,
Zipstream = False,
 

In the future, do something with the PDF and show the PDF to users to Approve or Cancel.
This will be done by; NeedsApprove = true.

If NeedsApprove is False, the order is Processed and can't be changed in TI. Like it is now.

 

 
       
       
 IN THE FUTURE: APPROVEORDER     
7Sends a request to the function: ApproveOrder().=> WebserviceUsername (string),
WebservicePassword (string),
CustomerUsername (string),
OrderId (string)		  
8  Receives the approve and checks the credentials and the OrderId.   
9 <=Sends back a Success with the new CertificateNrResultCode (),
ErrorMessage (string),
CertificateNr (string)		This process takes too long at some labs. Maybe this won't be workable...so maybe the CertificateNr return won't be possible. In this case, leave the CertificateNr empty. TerraIndex will read it from GetOrderStatus calls.1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
10Receives the CerificateNr and saves it.     
       
 IN THE FUTURE: CANCELORDER     
7Sends a request to the function: CancelOrder().> WebserviceUsername (string),
WebservicePassword (string),
CustomerUsername (string),
OrderId (string)		  
8  Receives the cancel and checks the credentials and the OrderId.   
9 <=Sends back a Success ResultCode (),
ErrorMessage (string)		 1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
10Removes the OrderId and the IsSend to False   If OrderIsAleadyApproved, set the values to Approved and keep the OrderId and IsSend. 
       

Create Order

Request example

public CreateOrderResponse.Response SendLabAssignment(string WebserviceUsername, string WebservicePassword, string CustomerUsername, string customerid, string sikbVersion, string assignmentXML, string languageCode, bool needsApprovalIsSupported = false)

        {

            CreateOrderResponse.Response set = new CreateOrderResponse.Response();

            try

            {

                bool useZipstream = true;

                MultipartFormDataContent content = new MultipartFormDataContent();

                //Add Formdata

                var formDataDictionary = new[]

                {

                    new KeyValuePair<string, string>("userName", WebserviceUsername),

                    new KeyValuePair<string, string>("password", WebservicePassword),

                    new KeyValuePair<string, string>("customerUserName", CustomerUsername),

                    new KeyValuePair<string, string>("clientId", customerid),

                    new KeyValuePair<string, string>("sikbVersion", sikbVersion),

                    new KeyValuePair<string, string>("languageCode", languageCode),

                    new KeyValuePair<string, string>("useZip", useZipstream.ToString() ),

                    new KeyValuePair<string, string>("needsApprovalIsSupported", needsApprovalIsSupported.ToString() ),

                    //new KeyValuePair<string, string>("orderXml", ZipStreamHelper.CompressToBase64String(assignmentXML)),

                    //new KeyValuePair<string, string>("orderXml", assignmentXML),

                };               

                foreach (var item in formDataDictionary)

                {

                    content.Add(new StringContent(item.Value), $"\"{item.Key}\"");

                }

                string filexml = string.Empty;

                if (useZipstream)

                {

                    filexml = ZipStreamHelper.CompressToBase64String(assignmentXML);

                }

                else

                {

                    filexml = assignmentXML;

                }

                //Add filecontent

                var fileContent = new ByteArrayContent(ZipStreamHelper.stringToByteArray(filexml));

                fileContent.Headers.ContentDisposition =

                        new System.Net.Http.Headers.ContentDispositionHeaderValue("form-data") //<- 'form-data' instead of 'attachment'

                        {

                            Name = "\"orderXml\"", // \" is needed so the message contains the quotes, wihtout it will fail

                            FileName = "\"VivaTerraIndexAssignment.xml\""

                        };

                fileContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/xml");               

                content.Add(fileContent);

                //Start sending

                HttpResponseMessage response = _HttpClient.PostAsync(_HttpClient.BaseAddress + "/CreateOrder", content).Result;

                response.EnsureSuccessStatusCode();

                string responseMessage = response.Content.ReadAsStringAsync().Result;

                if (string.IsNullOrEmpty(responseMessage))

                {

                    throw new Exception("Empty response from: [" + _HttpClient.BaseAddress + " /CreateOrder" + "]");

                }

                using (var ms = new System.IO.MemoryStream(System.Text.Encoding.UTF8.GetBytes(responseMessage)))

                {

                    XmlSerializer serializer = new XmlSerializer(typeof(CreateOrderResponse.Response));

                    set = (CreateOrderResponse.Response)serializer.Deserialize(ms);

                }

                //Can contain a PDf with price information

                if (set.UseZip && !string.IsNullOrEmpty(set.FileContent))

                {

                    //convert from base64 string back to normal

                    set.FileContent = ZipStreamHelper.DecompressBase64StringToString(set.FileContent);                   

                }

            }

            catch (Exception ex)

            {

                #region handle exception

                set.Status = new BusinessEntities.LabRestService.CreateOrderResponse.ResponseStatus();

                set.Status.StatusCode = ((int)ResultCodes.GeneralError).ToString();

                set.Status.ErrorMessage = "Exception occurred in CreateOrder (username: " + WebserviceUsername + ") with message: " + ex.Message;

                ex.Data.Add("WebserviceUsername", WebserviceUsername);

                ex.Data.Add("WebservicePassword", WebservicePassword);

                ex.Data.Add("CustomerUsername", CustomerUsername);

                ex.Data.Add("sikbVersion", sikbVersion);

                ex.Data.Add("customerid", customerid);

                ExceptionHandler.HandleException(ex);

                #endregion

            }

            return set;

        }

POST https://<URL>/CreateOrder HTTP/1.1

Content-Type: multipart/form-data; boundary="28a3e130-70c9-4a1a-b544-a802a1ade6ca"

Host: 81.175.89.24

Content-Length: 5010

Expect: 100-continue

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="userName"

<Webservice_Username>

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="password"

<Webservice_Password>

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="customerUserName"

<Customer_Username or token>

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="clientId"

300

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="sikbVersion"

13.4.0

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="languageCode"

nld

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="useZip"

True

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Type: text/plain; charset=utf-8

Content-Disposition: form-data; name="needsApprovalIsSupported"

False

--28a3e130-70c9-4a1a-b544-a802a1ade6ca

Content-Disposition: form-data; name="orderXml"; filename="VivaTerraIndexAssignment.xml"

Content-Type: application/xml

<SIKB File in Zip stream Base64  encoding>

--28a3e130-70c9-4a1a-b544-a802a1ade6ca--

Response example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<Response>

<OrderId>7113828</OrderId>

<NeedsApproval>True</NeedsApproval>

<FileContent></FileContent>

<Status>

    <StatusCode>1</StatusCode>

    <StatusCodeDescription>OK</StatusCodeDescription>

    <ErrorMessage></ErrorMessage>

</Status></Response>

Get Order status and Results

Oplossing/Design

TerraIndex gaat opvragen per licentie, welke resultaten en klaar staan. Deze worden opgevraagd als de nieuwste wijzigingen nieuwer zijn dan de laatste keer checken. Zo downloaden we nooit onnodig teveel en is het altijd nogmaals op te vragen.
 

ActionTerraIndex LaboratoriumParameters/MessageRemarksResultCodes
1Sends a request to the function: GetCustomers().> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string)		We want to skip the Password of the customer, and we introduce the WebserviceUsername + WebservicePassword. 
2  Receives the request and check the customers this username and searches the dateLastChanged for this Customer.   
3 <=Sends back the list of customers with the lastChangedTimestampResultCode (),
ErrorMessage (string),
List<customer> , Customer:
CustomerCode (string),
CustomerName (string),
LabID (int),
LabName (string),
ChangedTimeStamp (DateTime)		We receive the dateTimestamp instead of sending it, so we always get the full list and we are also able to delete customercodes.1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
4Receives the list of Customers. Read the Timestamp this Customer is last checked for Results/Statuses.     
5Send for each Customer a  call to retreive all orders statuses changes since a certain timestamp.
Function: GetOrderStatuses()		> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string),
CustomerCode (string),
LastCheckedTimestamp (DateTime)		TerraIndex keeps track of the last check timestamp for each license. 
6  Receives the request and check the orders that are changed since the timestamp for this Customer.   
7 <=Sends back the list of orders with the status and lastChangedTimestampResultCode (),
ErrorMessage (string),
OrderID (string),
LabassignmentGUID (GUID),
CertificateNumber (string)
OrderStatusSIKB (int),
Delayed (boolean),
ExpectedTimeStamp (DateTime),		OrderStatusSIKB is the SIKB Labassignment status.

Delayed is a boolean to tell the customer a order will be later ready then expected. The ExpectedTimestamp.
If Delayed for the firsttime, TerraIndex can send a notification to the users and show a different layout.

LabassignmentGUID is filled to support also Labassignments that are not from TerraIndex Ordered.		1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
8Receives the list of Orders with status.
Update the CertificateNr if this is not already present in the labassignment. 		   CertifcateNumber could be new here, if the lab wasn't able to fill it directly at the ApproveOrder. 
9Send for each Order a call to retreive all results.
Function: GetOrderResults()		> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string),
CustomerCode (string),
OrderID (string),
SIKBVersion (string, default: '13.4.0')		Besides SIKB 13.4.0, TerraIndex also supports 9.0.0/8.0.0 etc. 
10  Receives the request and creates a SIKB results file based on the version that is requested.   
11 <=Sends back the results of the orders.ResultCode (),
ErrorMessage (string),
OrderId (string),
LabassignmentGUID (GUID),
FileContent_Base64 (string),
UseZipStream/UseZip (bool, default: 'false'),		 1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
12Receives the results and imports all results.   

Import will be done to corresponding samples based on:

  • Find Project by ProjectGUID (as provided in the labassignment)
  • Find Project by ProjectCode (as provided in the Labassignment)
  • Find Project and Labassignment by LabassignmentGUID (as provided in the Labassignment)
  • Find Project (only if Project is not found yet) and Samples based on SampleGUID (as provided in the Labassignment) .
    Sample GUIDs that are send to the lab in the labassignment version SIKB 13 or higher are required in the results for labassignment.
    For lower version Labassignments the lab should return the 'old' idanlmons as SampleGUID in the XML.
  • Find Samples (only if Project is already found ) by SampleName

What is imported?

  • If Sample is found, the results in the XML are always all updated and/or inserted.
  • If Project is found, but the sample is not; The Sample and the results are inserted as new Sample. (If watersample; fake filtertube and fake measurementpoints are created)
 
13If OrderStatus is 'Completed/Reported' (SIKBID: 5)
Request the PDF certificate.
Function: GetOrderPDF()		> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string),
CustomerCode (string),
OrderID (string),		  
14  Receives the request and creates the PDF for the Order.   
15 <=Sends back the PDF of the order.ResultCode (),
ErrorMessage (string),
OrderId (string),
LabassignmentGUID (GUID),
FileContent_Base64 (string),
UseZipStream/UseZip (bool, default: 'false'),		If the PDF is not available yet, please give the resultcode: PDFNotAvailable.1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
12Receives the PDF and stores it for reporting and downloading.     


Customer wants to see real time information about the status in the interface

Oplossing/Design

Om in de interface van TerraIndex altijd up to date informatie te tonen als een gebruiker een labopdracht opent om de status te zien, hergebruiken we een deel van de GetOrderStatus, maar dan met specifiek een OrderID.

..NOT SUPPORTED YET...

ActionTerraIndex LaboratoriumParameters/MessageRemarksResultCodes
1Request the Order status for a single Order/Labassignment.
Function: GetOrderStatus()		> WebserviceUsername (string), 
WebservicePassword (string),
CustomerUsername (string),
CustomerCode (string),
OrderID (string),		  
2  Receives the request and gets the status for the Order.   
3 <=Sends back the status of the order.ResultCode (),
ErrorMessage (string),
OrderID (string),
LabassignmentGUID (GUID),
CertificateNumber (string)
OrderStatusSIKB (int),
Delayed (boolean),
ExpectedTimeStamp (DateTime),		OrderStatusSIKB is the SIKB Labassignment status.

Delayed is a boolean to tell the customer a order will be later ready then expected. The ExpectedTimestamp.
If Delayed for the firsttime, TerraIndex can send a notification to the users and show a different layout.

LabassignmentGUID is filled to support also Labassignments that are not from TerraIndex Ordered.		1 = Success,
2 = GeneralError,
3 = WrongSIKBVersion,
4 = InvalidCredentials,
5 = CustomerUsernameInvalid,
6 = CustomerUsernameNotValidForCustomerCode
7 = FileContentProblem,
8 = InvalidOrderId,
9 = OrderIdAlreadyApproved
10 = PDFNotAvailable
4Receives the status and shows in the interface the updated info.
Update the CertificateNr if this is not already present in the labassignment. 		   CertifcateNumber could be new here, if the lab wasn't able to fill it directly at the ApproveOrder.