Getting started

 

Welcome to the BoldIQ Developer Portal. This guide gets you quickly up and running using the API’s.

 

Prerequisites:

  • Postman. Download postman app from www.getpostman.com
  • Start postman, click on Import the json file (close to top left corner)
  • Replace any instance of <Replace with Subscription Key> with your subscription key that can be found under User Profile on the BoldIQ developer portal

 

Note:

  • You currently have to create a schedule for a calendar day before creating (using POST) workers or jobs to that day. PUT operations are still OK since they don't currently affect the schedule

 

 

Example workflow:

 

1. Delete Run

  • This will delete all resources (workers/jobs/schedule/config) associated with the given date.
  • The response will include information about how many resources of each type that was deleted.

 

2. Get Workers

  • This returns an empty array since we haven't added any workers yet.

 

3. Get Jobs

  • This will return an empty array since we haven't added any jobs yet.

 

4. Put workers

  • This will replace all existing workers with a new set of workers that are specified in the body of the request.
  • The response will indicate how many existing workers were replaced. It will be zero since there are no existing workers.
  • Note: "PUT" operations does not affect the schedule. I.e. a schedule needs to be created after any put operation.
  • Note: workers are currently required to have a unique user provided "WorkerId".
  • For worker Start/End Location, only Latitude/Longitude fields are used (automatic geocoding is currently not enabled).
  • For Worker Start/End Time, only the Time portion of the DateTime is used. I.e. a StartTime "09:00:00", "2017-02-02T09:00:00", "2001-01-01T09:00:00" are all equivalent. The date is given in the url, e.g. "https://gsapi.azure-api.net/api/calendar/2017-02-02/workers".

 

5. Put Jobs

  • Similar to "Put workers" but for jobs (demand).
  • Note: jobs are currently required to have a unique user provided "JobId".
  • "Duration" for a job is specified in minutes.

 

  • You can now go back to step 2) and 3) to invoke "Get Workers" or "Get Jobs", you will see the workers/jobs you just set.

 

6. Create schedule

  • Creates and starts optimizing a new schedule given the jobs/workers that we just added.
  • Any existing schedule is replaced by the new schedule.
  • The optimization time in seconds is given in the request body.

 

7. Get Schedule

  • Retrieves the schedule for given date.
  • ScheduleOptimizationStatus indicates if the schedule is still being optimized.
  • When optimization is done (status 4), the schedule is available – the "ScheduleJobs" field.

 

8. Get worker "John_E_Bellevue"

 

10. Availability Check

  • In this step, we want to check if we have necessary resources to accept a new job. This check does not alter the existing schedule in any way.
  • The job we want to check require skills "ELECTRIC" and "PLUMBING". It’s a job estimated to take 120 minutes, located in Kirkland. In this example, we want to check if it is possible to start this job either between 9am and 10am OR between 2pm and 3pm on 2017-02-02.
  • Execute the Availability check and look at the response. It now shows that we have availability for both time windows.

 

11. Book Job

  • Now that we checked that we have available resources on 2017-02-02 to start the job between 2pm and 3pm, let’s try and actually add the job to the schedule.
  • Note that availability may have changed between the availability check and adding the job.
  • Default behavior when adding a job is that it will fail if we no longer have availability (This can be overridden so we can add the job even if we cannot fit it in our current schedule).
  • If the job was successfully added, our schedule is also automatically updated.
  • I.e. if you once again execute "Get Schedule", you should see the 120-minute job in kirkland in the schedule, assigned to Jeff_PE_FederalWay.

 

12. Add a new worker

  • In this step, we're adding a new worker - Eric_PEW_Seattle
  • After executing "Add Worker", once again have a look at the current schedule by calling "Get Schedule".
  • Note: the schedule hasn't changed after adding the new worker. However, to make sure we get an optimized schedule after adding new resources, we need to reoptimize the schedule. Do this by executing "Create Schedule" again.
  • After executing "Create Schedule", execute "Get Schedule".
  • Note: the response of "Get Schedule" may have an "OptimizationStatusString" other than "OptimizationDone", e.g "OptimizationInProgress". Remember that we specified max allowed optimization time in the request body when creating the schedule (In our example this is set to 10s). If you see an OptimizationStatusString set to OptimizationInProgress, simply try executing Get Schedule again after 10s has passed.
  • You will now have a new optimized schedule.