API
      Back to home
      1. VROMO Help Centre
      2. Integrations
      3. API

      Create Job on a Site (JavaScript example)

      Demos of how to create jobs on a site in the VROMO app

      This article provides sample JavaScript code for creating jobs on VROMO for the purpose of integrating with another system such as a Point of Sale.

      At each step, the code will build upon the previous steps to create a more complete or robust integration. For your requirements, you may not need to use the final example, or you may wish to use any step as a template for your own integration.

      Throughout this article, we hardcoded many values of the job request body. In practice, these would be variables passed in from previous steps. For example, the job "name", contact "name", "phone", and "email", the additional attributes i.e. "attr", the "timeframe"s for setting the deadlines. These would either be calculated or provided as input.

      1. Create Job on a Site

        Creating a job on a site by the Site Id provided in the endpoint URL. In the example below: "288045805830145".

        Response JSON:
        Note there are only two tasks as there is no blueprint assigned to the site to transform the job. This will be discussed in the next step.

      2. Create Job on a Site with a Blueprint Assigned

        If you assign a blueprint to a Site the job will transform based on the blueprint.
        The blueprint is an abstraction that transforms jobs into a certain amount of tasks, each task being either "arrival" or "delivery", having constraints such as geofencing, radius for geofencing, auto swiping, manual swiping, deadlines, require photo, require signature.

        A blueprint can be assigned to a site through the app by going to Sites -> Select Site -> Blueprint -> Select Blueprint

        Or through the API by updating the site. There is an example in the API documentation. To view the example, on the right-hand side of the page is a dropdown called "Example" and an option called "Update/Assign a Site's Blueprint". This will provide you the payload to PATCH to the "sites" endpoint.

        After assigning the blueprint to the site and posting the same payload as in step 1 again, the response is different as the blueprint transforms the job's tasks. Note, in particular, the number of tasks, "constraints", and the task "names".

      3. Fetch Site by Site Name then Create Job on Site

        You may wish to programmatically find a site and use that site to create a job on it.

        To do so, use a GET request to the sites endpoint, then create the job as before:

      4. Fetch Site by Site Name, Create a Site if None Found, Then Create Job on Site

        Following on from step 3, if there is no site found you may wish to create a site and then create the job on that new site.

        This allows the integration to be future-proofed as new stores/restaurants/pickup locations can be added without any manual intervention.

        The process flow will be to fetch all sites, filter on the site name provided, if there is no match, then create the site (with a blueprint attached). Then create the job.

      5. Using Google Maps API to Get the Latitude/Longitude Coordinates

        If we do not have access to the latitude and longitude for the site or customer's address we can use the Google Maps Geocode API to query addresses to get them.
        We will be using the following code to query addresses to the Google Maps API.
        Next, we will add this call to our code from Step 4:

      6. Handling Error Cases

        We should be conscious there are potential errors that may occur depending on the input.

        For instance, if the site coordinates and the delivery coordinates are not within reasonable proximity of each other the job will fail to be created. Therefore if the address provided to Google Maps API is not specific enough and Google Maps API finds an incorrect match or the Google Maps API call fails and hits the "catch", returning "0, 0", the job may fail to be created. We want the jobs to always be created on VROMO and allow the users to make any corrections needed.

        Should the job fail to be created we will simply try to create the job again with the delivery coordinates set the same as the site's coordinates to ensure both are in proximity to each other. The driver or dispatcher should notice the incorrect coordinates and address the issue manually.