JobsManager

1
2
3
4
5
6
7
8
9
10
11
// Provide details for the file attachment to add to the job
const attachmentDetails: JobAttachmentDetails = {
  jobId: 'job3',
  attachment: file, // File uploaded from a file upload form
  alias: 'Location 1 Photo',
  folder: 'images'
};
// Add the attachment
const results: AddJobAttachmentResponse = await jobsManager.addAttachment(attachmentDetails);
const attachmentId = results.attachmentId;
const attachmentUrl = results.url; // Url to access the attachment

1
2
3
4
5
6
7
8
9
10
// Provide details for the linked attachment to add to the job
const attachmentDetails: JobAttachmentDetails = {
 jobId: 'job3',
 url: 'https://domain.hostname.com/doc',
 alias: 'Documentation Link',
 folder: 'info'
};
// Add the attachment
const results: AddJobAttachmentResponse = await jobsManager.addAttachmentLinked(attachmentDetails);
const attachmentId = results.attachmentId;

1
2
3
4
5
6
7
8
9
10
11
12
13
// Add a dependency to a step on a job.
// Step step5a on job3 cannot be run until job8 step11 has completed.
const dependencyDetails: JobDependencyDetails = {
 jobId: 'job3',
 stepIds: ['step5a'],
 dependentJobId: 'job8',
 dependentStepId: 'step11'
};
const result: JobActionResponse = await jobsManager.addDependency(dependencyDetails);
const stepResponses = result.stepResponses;
stepResponses.forEach(response => {
 console.log(`Step ${response.stepId}: status ${response.status}`);
});

1
2
3
4
5
6
7
8
9
10
11
12
// Add a hold to multiple steps on a job. The hold has an expiration date and will be released on that date.
// If the hold did not have an expiration date, it will need to be released manually by calling releaseHolds.
const holdDetails: JobHoldDetails = {
 jobId: 'job3',
 stepIds: ['step5a', 'step5b'],
 scheduledRelease: new Date(2025, 11, 17)
};
const result: JobActionResponse = await jobsManager.addHolds(holdDetails);
const stepResponses = result.stepResponses;
stepResponses.forEach(response => {
 console.log(`Step ${response.stepId}: status ${response.status}`);
});

1
const commentId: string = await jobsManager.addJobComment('job3', 'Impediment encountered while at the job site.');

1
const success: boolean = await jobsManager.assignCurrentStep(jobId, 'cjones', AssignedType.User);

1
const success: boolean = await jobsManager.assignStep(jobId, 'step7a', 'cjones', AssignedType.User);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Example 1:
// Return the number of jobs found with one or more properties with the string 'Parcel', grouped by priority.
const parcelSearch: JobStatisticsDetails = {
  search: 'Parcel',
  groupBy: 'priority'
};
// Get the results
const results: JobStatistics = await jobsManager.calculateJobStatistics(parcelSearch);

// Example 2:
// Return the number of jobs found that match a search criteria, grouped by job status.
// This query returns the number of open jobs assigned to one of two groups.
const jobStatusDetails: JobStatisticsDetails = {
  q: '"assignedType=\'Group\' AND closed=0 AND assignedTo IN (\'groupId123\', \'groupId456\')"',
  groupBy: 'job_status'
};
// Get the results
const results: JobStatistics = await jobsManager.calculateJobStatistics(jobStatusDetails);
const totalNumber = results.total;
const groupedValues: GroupedValue[] = results.groupedValues; // Total values divided into sections

1
2
3
4
5
6
7
8
9
10
11
// Provide optional overrides for just the properties that need to be overwritten.
const jobOverrides: CreateJobOverrides = {
  numberOfJobs: 2,
  assignedType: AssignedType.User,
   assignedTo: 'cjones'
};

// Create jobs
const results = await jobsManager.createJobs('jobTemplate1', jobOverrides);
const createdJobIds: string[] = results.jobIds;
const automatic: boolean = results.autoExecuted;

1
2
3
4
5
6
const response: JobActionResponse = await jobsManager.finishSteps(jobId, ['step7a', 'step7b']);
const success = response.success;
response.stepResponses.forEach(stepResponse => {
 // Do something with the step responses
 console.log(`Step ${stepResponse.stepId}, status: ${stepResponse.status}`);
});

1
2
3
4
// Get the attachment url
const url: string = await jobsManager.getAttachmentUrl('job3', 'attachment7');
// Open the link to download a file attachment or view a linked attachment
window.open(url);

1
2
3
4
5
6
7
// Get the list of attachments for the job
const attachments: JobAttachment[] = await jobsManager.getAttachments('job3');
const numAttachments = attachments.length;
attachments.forEach(attachment => {
 // Do something with each attachment
 console.log(`Attachment ${attachment.alias}, id=${attachment.id}, url=${attachment.url}`);
});

1
2
3
4
5
6
7
// Options to retrieve hold information for the job
const options: JobRequestOptions = {
  holds: true
};

// Get the job with basic details and hold information
const job = await jobsManager.getJob('job1', options);

1
2
3
4
5
const comments: JobComment[] = await jobsManager.getJobComments('job3');
comments.forEach(comment => {
 // Do something with the comments
 console.log(`Comment ${comment.comment}, submitted by ${comment.lastModifiedBy} on ${comment.lastModified}`);
});

1
2
3
4
5
6
7
8
9
const history: JobHistory[] = await jobsManager.getJobHistory('job3');

// Do something with the history
// Get the duration in seconds of how long it took to complete a step on the job
const history: JobHistory[] = [];
const finishedEntries = history.filter(h => h.action === JobHistoryAction.Finished)
finishedEntries.map(entry => {
 console.log(`Job ${entry.jobId}, step ${entry.stepId} was finished on ${entry.endDate} in ${entry.durationSeconds} seconds`);
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Example 1:
// Search for jobs using a simple search.
// This query returns jobs with the text 'Wetlands' in its properties, with the specified fields, and returns the first 1000 matches.
const simpleSearch: Query = {
 search: 'Wetlands',
 fields: ['jobId', 'jobName', 'jobStatus', 'priority'],
 start: 0,
 num: 1000
};
// Query for the results
const queryResults = await jobsManager.queryJobs(simpleSearch);

// Example 2:
// Search for jobs using multiple qualifiers.
// This query returns jobs that are not closed and are assigned to 'cjones', with the specified fields,
// and sorted by jobName then priority.
const query: Query = {
 q: '"assignedType=\'User\' AND closed=0 AND assignedTo=\'cjones\'"',
 fields: ['jobId', 'jobName', 'jobStatus', 'priority'],
 sortFields: [
   {field: 'jobName', sortOrder: SortOrderType.Asc},
   {field: 'priority', sortOrder: SortOrderType.Desc}
 ],
 start: 0
};

// Query for the results
const queryResults = await jobsManager.queryJobs(simpleSearch);
const rows = queryResults.results;

1
2
3
4
5
6
const response: JobActionResponse = await jobsManager.setCurrentStep(jobId, 'step7b');
// const success = response.success;
response.stepResponses.forEach(stepResponse => {
 // Do something with the step responses
 console.log(`Step ${stepResponse.stepId}, status: ${stepResponse.status}`);
});

1
2
3
4
5
6
7
const point = new Point({
 x: -111.3,
 y: 52.68
});

// Update the job location
const result: boolean = await jobsManager.setJobLocation('job1', point);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// Start multiple steps, receive a StepInfoRequired message for one of the steps, and respond to server with a response.
// In this example, one of the started steps was a Question step. The server will send a StepInfoRequired message for
// the Question step and will wait for a response back to continue with the step.
// There is also a handler for when a step finishes running on the job.

// Get an instance of a NotificationManager
const jobId = 'job3';
const notificationManager = await ManagerFactory.getManager(NotificationManager, options);

// Created a handler for a StepInfoRequired message for a Question step.
const handleQuestionStepInfoRequired = (message: MessageDetails) => {
 // Types are not defined for each type of MessageDetails at this point, so need cast to any.
 const messageAsAny = message as any;
 const stepId: string = messageAsAny.stepId;
 const question: string = messageAsAny.question;
 type QuestionResponseType = {name: string, value: number};
 const questionResponses: QuestionResponseType[] = messageAsAny.questionResponses; // Options available to select from
 const canComment: boolean = messageAsAny.canComment;

 // Typically, the user would be prompted with the question and list of possible options to select from.
 // When a selection is made, the response would be sent back to server so that running of the step can continue.
 // In this example, use the first option in the list of questionResponses as the response to send back to server.

 // Construct the question response
 const selectedOption = questionResponses[0];
 const questionResponse = {
   msgType: 'StepInfoResponse',
   message: {
     jobId: message.jobId,
     stepId,
     questionResponse: selectedOption.value,
     comment: `User selected option ${selectedOption.name}` // Optional comment if a comment is allowed in the step
   }
 };
 // Send the question response to server
 notificationManager.send(questionResponse);
};

// Create a handler for job notification messages
const handleJobMessages = (message: NotificationMessage): Promise<void> => {
 switch (message.msgType) {
   case('StepInfoRequired'):
     handleQuestionStepInfoRequired(message.message);
     break;
   case ('StepFinished'):
     const stepIds: string[] = (message.message as any).stepIds;
     console.log(`Steps ${stepIds.join(', ')} were completed in job ${message.message.jobId}`);
     break;
   default:
     break;
 }
};

// Subscribe to job notifications for a job.
// Job notification messages will automatically get sent to the message handler 'handleJobMessages'.
const callbackId = notificationManager.subscribeToJob(jobId, handleJobMessages);

// Start steps on the job
const jobsManager = await ManagerFactory.getManager(JobsManager, options);
const response: JobActionResponse = await jobsManager.startSteps(jobId, ['step7a', 'step7b']);
const success = response.success;
response.stepResponses.forEach(stepResponse => {
 // Do something with the step responses
 console.log(`Step ${stepResponse.stepId}, status: ${stepResponse.status}`);
});

1
2
3
4
5
6
const response: JobActionResponse = await jobsManager.stopSteps(jobId, ['step7a', 'step7b']);
const success = response.success;
response.stepResponses.forEach(stepResponse => {
 // Do something with the step responses
 console.log(`Step ${stepResponse.stepId}, status: ${stepResponse.status}`);
});

1
2
3
4
5
6
7
8
9
// Provide details for updating an existing attachment
const attachmentDetails: JobAttachmentDetails = {
  jobId: 'job3',
  attachmentId: 'attachment7',
  alias: 'Location 2 Photo',
  folder: 'images2'
};
// Update the attachment
const success: boolean = await jobsManager.updateAttachment(attachmentDetails);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
// Include just the properties that require updating in the job
const jobUpdates: UpdateJobOverrides = {
 // Update basic properties
 jobStatus: 'In Progress',
 priority: 'Medium',

 // Update extended properties
 extendedProperties: [
   // Update 2 properties in table1 and 1 property from table2
   {identifier: 'table1.property3', value: '4'},
   {identifier: 'table1.property4', value: 'Zone8'},
   {identifier: 'table2.property5', value: 'Parcel3'}
 ],

 // Update related properties
 relatedProperties: {
   adds: [
     {
       tableName: 'table3',
       entries: [ // Add 2 rows to table3
         {properties: [{propertyName: 'property7', value: 'true'}, {propertyName: 'property8', value: '12.6'}]},
         {properties: [{propertyName: 'property7', value: 'false'}, {propertyName: 'property8', value: '17.3'}]},
       ]
     }
   ],
   updates: [
     // Update a row in table4 and table5
     {
       tableName: 'table4',
       entries: [
         {id: '1000001', properties: [{propertyName: 'property10', value: '10000'}, {propertyName: 'property11', value: 'cjones'}]}
       ]
     },
     {
       tableName: 'table5',
       entries: [
         {id: '1200002', properties: [{propertyName: 'property14', value: '19.1'}, {propertyName: 'property15', value: 'Z12'}]}
       ]
     }
   ],
   deletes: [
     // Delete a row from table6 and 2 rows from table7
     {tableName: 'table6', ids: ['1300001']},
     {tableName: 'table7', ids: ['1500008', '1500009']},
   ]
 }
};

// Update the job
const result: boolean = await jobsManager.updateJob('job1', jobUpdates);