UpdateStatus is used inside Batch Jobs to relay specific information about what is happening inside the Batch Job while it is running. It can be used in conjunction with GetStatus to view the data that UpdateStatus reports, or you can query EP_Profile_Configuration_Instance_BatchRuns using the WindowsProcessId returned by StartBatchJob or GetStatus to view those records as well. This is because the service saves records to this database table. Because of this, the type of input for each service input is limited to the table column’s datatype.
Batch Jobs are processes that can be scheduled to run. They run outside of user interaction and are not initiated by button clicks or page loads like most processes unless you use StartBatchJob.
For example, if a user clicks a button that updates a database record and the process of doing this update takes five minutes, the site will wait for the process to finish before forwarding the user to the next page. This can be a problem because the user will be stuck waiting for the process to finish. This is also an issue because the page will only wait so long before it times out. StartBatchJob can be used to eliminate this problem because the Batch Job will run in the background once it is kicked off by the service.
This is useful in situations where you want to manually start a Batch Job because some business requirement will not allow you to schedule the Batch Job to run at the same time every day or every week, or in a case where the Job needs to run now but its not scheduled to run until late in the night.
UpdateStatus Use Examples
UpdateStatus Basic uses
Here we have two processes side by side, the first process kicks off the batch job, the second process is what is inside the batch job
We are going to focus on the second process. In that process we are getting a list of items and then looping on that list. Inside that loop, we insert those items into a table, then check for success. If the insert fails we increment an error counter and then update the status of the Batch Job, if the insert is successful we skip incrementing the error counter and update the status of the Batch Job with the UpdateStatus service, then it starts over.
This is a very simple use case but it shows that thought needs to be put into place before using UpdateStatus as it requires useful information coming into it for useful information to be obtained from it.
Here is the service configuration for this example:
You can see the message is set to “Still processing records.” which also means I could add an UpdateStatus right at the end of the process that passes in a message that simply says “Complete.” or “All records processed.”.
AddProcessedCount is set to 1 which will force it to only increment by one. ProcessedCount is left blank so it will not overwrite the counter that is being incremented. When using this UpdateStatus service, you could also have an UpdateStatus that sets that ProcessedCount to 0 prior to the for each loop running.
LastProcessed is set to the item number of the last item that was attempted to insert into the table. The next time an item goes through the loop and this is called, LastProcessed will get overwritten with the new item number.
EstimateCount is set to the number of records returned by the GetItems query which will be static the whole time.
UploadCount is set to the Index of the for each loop which would give us the number of total records run through the loop.
ErrorCount is set up to be the ErrorCount/Errors from the evaluate which would only increment if a record failed to process. At the end of the batch job, this will be useful when it comes time to handle the errors (return message to user, send email, etc).
As you can see, the process was specifically set up to pass info on the batch job into the UpdateStatus service call. This provided the useful information that might be needed if you wanted to inquire about the status of the batch job.
All of this information given to the UpdateStatus service is written to a database table and returned if the GetStatus service is used. It is the developer’s responsibility to build a batch job process in a way that useful information is passed to the UpdateStatus service.
If you enter in a name that doesn’t correspond to an existing Batch Job it will throw an error like this.
If you enter in a valid name of a Batch Job but it is not the name of the Batch Job that you are running you will run into this error.
Other errors you can run into will come from invalid data being entered into the fields.
- LastProcessed has a character limit of 50
- EstimateCount must be an integer
- UploadCount must be an integer
- ErrorCount must be an integer
- EndTime has a character limit of 50
- ProcessedCount must be an integer