Placing an order

Introduction

A major drawback in older real estate systems were that they relied on development by the system owner for adding new integrations.

Vitec Next replaces this with a configurable order flow, which means that no development is needed by Vitec to add a new integration. This in turns means no updates are necessary to allow a new integration to be released.

After an initial order is placed in Vitec Next all further information exchange is handled by Vitec Hub. Since Vitec Hub is an open API the partner has the ability to read and write the needed information without any further development.

This flow creates a loose technical coupling between Next and the partners system, which allows them to be developed separately with separate deployment schedules. The user will still experience it as two closely integrated systems though.

Selling an estate in Next

A guid for product developers & testers

This is a short description on how to create and sell a real estate using Vitec Next. This is primarily meant as a short introduction for third party contributors in case of testing, with the use of the database VITECPARTNER. Different databases may have different configuration.

1. Login to Next with earlier given credentials.
2. Create a new assignment by clicking + in the top menu and then “Nytt objekt”
3. Enter the data for the assignment and save it
4. Go to the page “Oppdragsparter”, select “Utfør” and “Ny oppdragspart”. Relasjonstype must be “Selger”
5. Add a new contact or search for an existing one
6. Go to the page “Oppdragsavtale”, section “Budsjettoppstilling”, click on the Edit pen, then “Forslag”, save the suggestionGo to the page “Oversikt”, click on “Sjekkliste”, click on “Oppdrag signert” and click “Lagre” on the panel
7. The assignment is now accepted and orders can be placed from it
8. Go to the page “Oversikt”, click on “Sjekkliste”, section “Markedsføring”, click on “Selger har godkjent salgsoppgave”
9. The assignment is now ready for marketing and bids can be placed
10. Go to the page “Bud og omsetning”, select “Utfør” and then «Omset uten bud»
11. Add dates and times as needed, who the buyer is and price for the sale and then Save
12. The assignment is now sold

Order flow

The general flow an order follows is described below. For an in-depth explanation of each step, see the technical description.

1. A user places an order in Next for a product.
   a) Open the estate, select “Marked og Tjenester”.
   
   b) Then, select and “Bestill Tjeneste”.

   

2. A HTTPS call is made from Next’s backend to the partner’s backend with information about the order
   Note! The URL length must not exceed 2047.
3. The partner responds to Next that they have received the order and has the optional choice of requesting a browser window. If needed, additional information can be fetched from Vitec Hub.
   Note! It’s important that the reply is done as quickly as possible since a timeout (30s) means that Next won’t understand that the order is received and subsequently will cancel the order in Next.
4. If a browser windows is presented, the user can select order details and confirm the order in the window
5. Order status updates can be sent to Next through Hub
6. When the order is complete (fully or in part= the material (documents, images etc.) are delivered through Hub.
7. Messages can be sent with information about the order and links to specific pages in Next
8. The order status is set to complete.

In-depth description of the order flow

The flow for an order

1. PLACING AN ORDER

A logged in user navigates to order page of an estate and select the partner and product that they wish to order. If the partner has several products, the user can be given a choice in step 4.

2. HTTPS call

A HTTPS call is made from the backend of Next to the partners web backend containing information about the order and authentication details. The partner decides the format of the link that Next opens, and the URL length must not exceed 2047. Note that all customers must have the same url template. The link can contain the following information:

• installationid: The id of the installation (ie database). Normally the entire installation for a chain. A few exceptions exist. This field will always contain a value.
• orderid: A unique id (guid) for every new order. This field will always contain a value.
• estateid: The only unique identifier for the estate. This field will always contain a value.
• deptid: Id of the department that the estate belongs to, unique within one installation but not between installations. Installationid + DeptId is a unique identifier for an office. This field will always contain a value.
• userid: Id of the user that placed the order, unique within one installation. This field will always contain a value. This user is not necessarily the broker that is responsible for the estate/sale, and could belong to a different department than the department id of the estate. A user can belong to multiple departments. This field will always contain a value.
• useremail: Email address of the above. This field will always contain a value.
• username: Full name of the above
• estateaddress: The street address of the estate
• matrikkel: As one string separated by a comma. Kommunenummer, gårdsnummer, bruksnummer, festenummer, seksjonsnummer. For example: 301,27,1737,0,0
• shareno: Organisationnumber for cooperative and share number as one string separated by a comma.
• assignmentno: The assignment number (oppdragsnummer), 4-0001/16. This number can have different formats for different chains and it’s not a unique id. EstateId must be used as the unique identifier for the estate. Assignment number is empty until the assignment agreement is signed.

Assignmentno, useremail, username and estateaddress will be url encoded.

Fields marked with bold will always contain a value (but is not required to be part of the URL if the partner do not want to). The template for the URL should include the needed placeholders. Note that even if all customers must have the same url template, the installationid can be used to identify the customer and it can be located in the query parameter, in the catalogue name or in the domain. Example of URL templates are:

An order link containing some fields

• https://order.partner.com/order.aspx?installationid=<installationid>&estateid=<estateid>&orderid=<orderid>

Two alternative formats

• https://order.partner.com/order/<installationid>/<estateid>/<orderid>
• https://order.partner.<installationid>.com/order/<estateid>/<orderid>

An order link containing all available fields

• https://order.partner.com/completeorder.aspx?installationid=<installationid>&estateid=<estateid>&orderid=<orderid>&userid=<userid>&username=<username>&useremail=<useremail>&matrikkel=<matrikkel>&shareno=<shareno>&assignmentno=<assignmentno>&deptid=<deptid>

Example of a substituted link

• https://order.partner.com/completeorder.aspx?installationid=MSNXTT&estateid=e408cb72-e80b-4dbf-9ad1-936345a71857&orderid=789b6eb2-ea5c-45e6-a7e6-a5bcd2b4bae7&userid=HSG&username=Henning+Strand-Gjesdal&useremail=henning.strand-gjesdal@vitecsoftware.com&estateaddr=Ankerveien+83&deptid=1&matrikkel=301,27,1737,0,0&shareno=&assignmentno=4-0001%2f16&deptid=1

Authentication

To validate requests from *Next and provice an opportunity for to implement single-sign-on we implement HMAC based verification on order request. The usae is described here
HMAC Signature for Order Validation (BETA)

Next uses one set of credentials to identify itself for all customers. The username and password is unique for each partner though. Identification is done by passing along username and password as basic authentication. Identification of the individual user and/or company can be done by checking installationid, departmentid and user email.

For more information about basic authentication, see client side authentication at http://tools.ietf.org/html/rfc2617 or http://en.wikipedia.org/wiki/Basic_access_authentication.

Language

Next has support for multiple languages. If you have the means you should check the language of the user placing the order by getting the language from the HTTP header Accept-Language. Language codes follow https://www.ietf.org/rfc/rfc1766.txt. As of January 2023 Next only has support for Norwegian Bokmål but we expect more languages to be added per customers’ requests. Language code for Norwegian Bokmål is nb-NO.

3. Confirming an order

When the partner receives an order it should be processed using the flow described below the important points.

It’s very important that the reply is done as quickly as possible. Authorize the call, save the needed the data and do processing after confirming that you’ve received the order. This due to multiple reasons:

1. A timeout (30s) means that Next won’t understand that the order is received and subsequently will cancel the order in Next.
2. The user that placed the order is actively waiting for confirmation. A slow response will create a bad user experience.

Confirmation flow

1. Check that the username and password for the superuser are correct. If not, return http status 401 and an error message (see below).
2. Validate that the user have the right to place an order in the partners system. The user should be linked to the partners user list using email address. If the user lacks rights to place an order or doesn’t exist the system can either:
   1. 1. automatically register a new user by using the provided user id and fetch user information from Hub using the function GET {installation}/Employees/{employeeId}
      2. return a http status code 302 with a Location-header with link to a web page allowing the user to register themselves and complete the order (with a pre-filled form from step a perhaps?)
      3. return a http status code 401 and an error message (see below).

   Error handling
   If an error occurs it’s possible to return a well-formatted error message to Next. The error can either be formatted as JSON or XML.
   
   XML:
   <next_error >
   <message>My error message.</message>
   </next_error>
   
   JSON:
   
{
"NextErrorMessage": "My Error Message"
}

   The message will be presented for the user and provide guidance to what they can do to rectify the error (For example:  Matrikkel is a required field for placing an order. We currently have maintenance, try again in 30 minutes). If possible, the error message should be in the requested language. The error message will be proceeded by “Feilmelding fra partnere”

   IMPORTANT! Next will only process an error page with starting the JSON or XML code described above. All other error messages will be ignored. Be sure to turn off any custom errors that for example .NET utilizes.
   

3. Create the order and then return either a http status code 200 if no more information is needed to complete the order or http status code 302 and the location header with a link if Next should open a browser window. The link should contain a token for the order (for example the order id given by Next). Send the response back to Next as soon as possible as the user is waiting for confirmation (see below for more information about the link)
4. Fetch any additional information needed through Hub. If you’re still fetching information when Next opens the link provided in step 2 the user should be presented with a loading page or similar.

Confirmation flow
The link returned to Next when answering with a 302 status code should be a direct link to the order. This link will be opened by the user’s web browser and thus there is a risk that user inadvertently / advertently modifies the link. Ie, use the information carefully. The same parameters used in the initial post can be used in this link.

After your 302 or 200 respose

After you return the 200 or 302 response code we perform necessary steps to fully complete the order in Next. We update state in the database and ticks off any checklist-point that this order should tick. Although it seldom does, this might also fail. In that place we delete the order card and allow the user to place a new order. If you have a product where only one order is allowed, some additional handeling is required in your end. Before denying a second order you should verify that the original order actually exists by calling GetOrderStatuses on Hub. A failed order will not be found and you can safely execute a new one.

4. Additional input from the user

The browser window opened by Next can be used to ask the user to specify options for the order. A photo order can for example allow the user to select if they only want images taken or if they want a video as well. Alternatively they can select a date and time for when the photographer should take the images.

When the user confirms the order, the browser window should be closed, as this will return the user to Next. A status update should be sent updating the order state to InProgress.

Each confirmed order is shown with an order card in Next showing the latest status, message and the optional link.

5. Status updates

The status of an order should be updated through Hub as the status changes. Use the function POST {installation}/Orders/{orderId}/Status to update the order status.

A status update does not necessarily contain a new status but only a new message / information text.

If an URL is provided the user will be able to open the provided link from Next. The link should then provide tokenized access to the order.

If a link to the order always should be available to the user, the link must be provided with every status update since links on old status updates are hidden to prevent the user from accessing old links. See more information about the link in section 4.

All status updates are shown in Next with the newest status on top.

The following order statuses are available:

• Created: The order has been created (Next sets this as default, no need to send)
• InProgress: The order is confirmed and the partner is working with processing / delivering the order. The message can be used to inform the user of the orderid in the partners system, cost, additional information etc. (see image above)
• InteractionRequired: The user needs to add information to complete the order. Link should always be provided for this status. This status is set automatically by Next if a 302 is returned and the link is saved.
• Error: There is a fatal error processing the order.
• Cancelled: The order has been cancelled. No further action can be taken
• Delivered: The order has been delivered. No further action can be taken

When the order status is changed to InteractionRequired, Error, Cancelled or Delivered the user will be notified using the internal message system in Next. The message contains information about which order has a new status and the new status. No HTML is allowed in the message, only plain text.

6. Deliver order

When the order is delivered any information (images, documents etc.) should be sent through Hub using the installationid and ordered given in step 1.

An order can be delivered in part or in full. For example, if the images of a photo order is complete but the video is not, deliver the images first and the video a couple of days later.

7. Cost and invoice

It’s possible to send cost and / or invoice for the order back to Next. Use the POST / PUT / DELETE Expense functions for this.

Each case need its own unique posting tag created in Next. This tag is used when calling Hub to identify how the cost should be handled. Ie, which account should be charged (buyer / seller / broker), which MVA rate should be used and should the amount be payed to the partners account / KID at settlement or not.

If the customer is lacking the posting code with the specific tag Hub will return 412, it’s important to have proper error handling to avoid mishandling of economic information.

See the document Next & Hub – Automation possibilities.

8. Messages

In addition to communicating with the user through status updates the partner can send messages to Next that shows up in the internal message system. These messages can contain more specific information and also direct links to pages in Next.

For example, if you’ve added a document to Next you can send a message notifying the user of the new document, name, category etc. and a link to the document page in Next. The users will receive information at their fingertips with direct links to what they should do Next. Links can be retrieved through POST {installationId}/Next/GetPath. Messages are sent using the POST {installationId}/Estates/{estateId}/SendMessage function.

The link can also be an external link.

No HTML is allowed in the message, only plain text.

8. The end

After delivering the information successfully, a final order status update should be done setting the status to completed.

Next can be configured to check items in the checklist when an order status has been set to Delivered. This configuration is done by the customer in each installation of Next. The customer can for example choose to advance their workflow when a specific order is delivered.

Administrative integration

In addition to have a trusted flow between Next and the partner system for ordering it’s also possible to have an integration for administration. The mechanics are the same as for ordering but with other parameters but the link is only available for users with full administrative privileges.
A HTTPS call is made from the backend of Next to the partners web backend. The partner decides the format of the link that Next opens. The link can contain the following information:

• installationid: The id of the installation (ie database). Normally the entire installation for a chain. A few exceptions exists. This field will always contain a value.
• userid: The userid of the administrator in Next opening the link. This field will always contain a value.

The flow is as follows:

1. Next sends a backend call to the partners system using the same basic authentication as for the order.
2. The partner checks that the username and password for the superuser are correct. If not, return http status 401
3. Validate that the user have the right to place an order in the partners system. If not, return http status 403
4. Return a http status code 302 with a link in the location header to the administration web page
5. Next opens the link in a new tab in the browser

By using this integration it’s possible to create a single-sign-on solution for administrative purposes, thereby eliminating the need for a separate login.
This can be used to allow the administrators to configure design, which part of application that should be available to the users etc.

Adding a product in Next

Before a product can be used, the customer needs to activate it. Available products are displayed in the Next settings pages under “products”.

When activation a product you can see and provide the following information:

Security

The partner system should always use HTTPS for all pages, both public pages and backend pages. This is to ensure that no sensitive information are transferred without encryption.
We encourage everyone to test their SSL certificates for weaknesses, for example by using https://www.ssllabs.com/ssltest/analyze.html
Separate credentials must be used for test and production.

Importance of features

	Must	Should	Optional
HTTPS order function	X
Order status updates	X
Informative error messages	X
Messages to user		X
Cost and invoice (see the Next automation)		X
Language support			X