# Job: Mobile Job Management

The job module provides many interfaces for applications to manage background job.

Developers can determine whether these interfaces work in the EdgerOS mobile App environment through the following code:

edger.env().then(data => {
  if (data.env === 'edgerapp') {
    // We work in EdgerOS mobile App environment.
  }
}).catch(error => {
  console.error(error);
});

# Functions

# edger.job.create(template, info, options)

Create a job that can be used for uploading or downloading.

• template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
• info {Object} Job execution information object.
• options {Object} Extra information object for the job.
• Returns: {Promise} Promise object, which is job information.

info is a job information object, it can contain the following members:

When the template is job_transport_upload_form:

• url {String} The upload file address.
• headers {Object} Custom headers. Optional.
• params {Object} Custom parameter information. Optional.
• tasks {Array} Upload tasks, the task object has the following items:
  • filePath {String} Path of the file.
  • fileType {String} Type of the file.
  • fileName {String} Name of the file.
  • uploadThumbnail {String} The thumbnail of file. Optional.
  • keyAlias {Object} A custom upload alias.

When the template is job_transport_download:

• headers {Object} Custom headers.
• tasks {Array} Upload tasks, the task object has the following items:
  • url {String} Where to download the file.
  • destPath {String} Path to download the file.
  • fileSize {Number} Size of the file (used to calculate download progress of the live picture). Optional.
  • fileType {String} Type of the file.
  • fileName {String} Name of the file.
  • fileExt {String} Extension of the file. Optional.
  • saveSystem {Boolean} If true, save to the system directory. If false, save to the EOS/ directory. Default is false. It only takes effect in Android. Optional.

headers is a job custom headers object, consisting of its case-insensitive name followed by a colon (:) and a value.

params is a job custom parameter information object, consisting of its case-insensitive name followed by a colon (:) and a value.

options is a job extra information object, it can contain the following members:

• timeout {Number} Timeout time. Optional.
• wifiOnly {Boolean} Jobs are created only when wifi is available. Optional.
• tags {Array} Custom tags used to identify jobs. Each tag item is a string. Optional.
• group {String} Job group name. Optional.
• validations {Object} Job group, consisting of its case-insensitive name followed by a colon (:) and a value. Optional.

Get the job object, it can contain the following members:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status. Optional values: start | pause | cancel | resume | done | error | progress.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const template = 'job_transport_upload_form'

const info = {
  url: `${window.location.origin}/api/form`,
  params: {
    storagePath: '/storagePath',
    uniqueId: 'xxx-xx-xx-xxx',
  },
  tasks: [{
    filePath: '/xxxx';
    fileType: 'picture';
    fileName: 'xxxx.png';
    keyAlias: {
      filePath: 'file'
    }
  }],
  headers: {}
}

const options = {
  timeout: 100, 
  wifiOnly: false, 
  tags: ['myjob']
}

edger.job.create(template, info, options).then((payload) => {
  const { id, job } = payload;
  console.log("Job created successfully. Job id:", id, "Job info:", job)
}).catch(error => {
  console.error(error);
});

# async / await

async function create(params) {
  try {
    const { template, info, options } = params;
    const { id, job } = await edger.job.create(template, info, options);
    console.log("Job created successfully. Job id:", id, "Job info:", job)
  } catch (error) {
    console.error(error);
  }
}

# edger.job.get(id)

Retrieve detailed information about the specified job.

• id {String} Job unique identification (Get all jobs without passing).
• Returns: {Promise<Array>} An array of job objects.

Get an array of job objects of type promise. Each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const id = 'xxxx-xxxxxx-xxxxx-xxxxx'

edger.job.get(id).then((payload) => {
  const { id, createdAt, updatedAt, status, job } = payload;
  console.log("Job info:", id, createdAt, updatedAt, status, job)
}).catch(error => {
  console.error(error);
});

# async / await

async function get(id) {
  try {
    const { id, createdAt, updatedAt, status, job } = await edger.job.get(id);
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  } catch (error) {
    console.error(error);
  }
}

# edger.job.pause([ids[, tags]])

Pause the execution of job.

• ids {Array} Array of job ids. Do not pass for operation all.
• tags {Array} Custom parameter information. Optional.
• Returns: {Promise} Promise array. Return an array of job objects.

Get a job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const ids = ['xxxx-xxxxxx-xxxxx-xxxxx']
const tags = ['custom tag1', 'custom tag2']

edger.job.pause(ids, tags).then((payload) => {
  payload.forEach((item) => {
    const { id, createdAt, updatedAt, status, job } = item;
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  })
}).catch(error => {
  console.error(error);
});

# async / await

async function pause(ids, tags) {
  try {
    const payload = await edger.job.pause(ids, tags);
    payload.forEach((item) => {
      const { id, createdAt, updatedAt, status, job } = item;
      console.log("Job info:", id, createdAt, updatedAt, status, job)
    })
  } catch (error) {
    console.error(error);
  }
}

# edger.job.cancel([ids[, tags]])

Cancel the job.

• ids {Array} Array of job ids. Do not pass for operation all.
• tags {Array} Custom parameter information. Optional.
• Returns: {Promise} Promise array. Return an array of job objects.

Get a job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const ids = ['xxxx-xxxxxx-xxxxx-xxxxx']
const tags = ['custom tag1', 'custom tag2']

edger.job.cancel(ids, tags).then((payload) => {
  payload.forEach((item) => {
    const { id, createdAt, updatedAt, status, job } = item;
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  })
}).catch(error => {
  console.error(error);
});

# async / await

async function cancel(ids, tags) {
  try {
    const payload = await edger.job.cancel(ids, tags);
    payload.forEach((item) => {
      const { id, createdAt, updatedAt, status, job } = item;
      console.log("Job info:", id, createdAt, updatedAt, status, job)
    })
  } catch (error) {
    console.error(error);
  }
}

# edger.job.resume([ids[, tags[, headers]]])

Resume the paused job.

• ids {Array} Array of job ids. Do not pass for operation all.
• tags {Array} Custom parameter information. Optional.
• headers {Object} Custom parameter headers. Optional.
• Returns: {Promise} Promise array. Return an array of job objects.

Get a job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const ids = ['xxxx-xxxxxx-xxxxx-xxxxx']
const tags = ['custom tag1', 'custom tag2']
const headers = {
  'custom-header': 'xxxxxxxxxxx'
}

edger.job.resume(ids, tags, headers).then((payload) => {
  payload.forEach((item) => {
    const { id, createdAt, updatedAt, status, job } = item;
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  })
}).catch(error => {
  console.error(error);
});

# async / await

async function resume(ids, tags, headers) {
  try {
    const payload = await edger.job.resume(ids, tags, headers);
    payload.forEach((item) => {
      const { id, createdAt, updatedAt, status, job } = item;
      console.log("Job info:", id, createdAt, updatedAt, status, job)
    })
  } catch (error) {
    console.error(error);
  }
}

# edger.job.retry([ids[, tags[, headers]]])

Retry the job.

• ids {Array} Array of job ids. Do not pass for operation all.
• tags {Array} Custom parameter information. Optional.
• headers {Object} Custom parameter headers. Optional.
• Returns: {Promise} Promise array. Return an array of job objects.

Get a job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const ids = ['xxxx-xxxxxx-xxxxx-xxxxx']
const tags = ['custom tag1', 'custom tag2']
const headers = {
  'custom-header': 'xxxxxxxxxxx'
}

edger.job.retry(ids, tags, headers).then((payload) => {
  payload.forEach((item) => {
    const { id, createdAt, updatedAt, status, job } = item;
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  })
}).catch(error => {
  console.error(error);
});

# async / await

async function retry(ids, tags) {
  try {
    const payload = await edger.job.retry(ids, tags);
    payload.forEach((item) => {
      const { id, createdAt, updatedAt, status, job } = item;
      console.log("Job info:", id, createdAt, updatedAt, status, job)
    })
  } catch (error) {
    console.error(error);
  }
}

# edger.job.updateStatus(ids, status)

Update the status of job.

• ids {Array} Array of job ids.
• status {String} The final status of job updates. Must be waiting、start、pause、cancel、resume、 done、error or progress.
• Returns: {Promise} Promise array. Return an array of job objects.

Get a job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • options {Object} Extra information object for the job.

# Example

const ids = ['xxxx-xxxxxx-xxxxx-xxxxx']
const status = 'done'

edger.job.updateStatus(ids, status).then((payload) => {
  payload.forEach((item) => {
    const { id, createdAt, updatedAt, status, job } = item;
    console.log("Job info:", id, createdAt, updatedAt, status, job)
  })
}).catch(error => {
  console.error(error);
});

# async / await

async function updateStatus(ids, status) {
  try {
    const payload = await edger.job.updateStatus(ids, status);
    payload.forEach((item) => {
      const { id, createdAt, updatedAt, status, job } = item;
      console.log("Job info:", id, createdAt, updatedAt, status, job)
    })
  } catch (error) {
    console.error(error);
  }
}

# edger.job.errorSummary()

Return an error summary of job execution.

• Returns: {Promise<Object>} Job error summary object.

Job error summary object includes:

• importSummary {Number} Summarize the import error count.
• importError {Number} Number of tasks currently importing status error.
• exportSummary {Number} Summary export error statistics.
• exportError {Number} Number of tasks currently exporting status error.

# Example

edger.job.errorSummary().then((payload) => {
  const { importSummary, importError, exportSummary, exportError } = payload;
  console.log("Job error summary:", importSummary, importError, exportSummary, exportError)
}).catch(error => {
  console.error(error);
});

# async / await

async function errorSummary() {
  try {
    const { importSummary, importError, exportSummary, exportError } =  await edger.job.errorSummary();
    console.log("Job error summary:", importSummary, importError, exportSummary, exportError)
  } catch (error) {
    console.error(error);
  }
}

# edger.job.history.query(params, options)

Query the historical execution records of job.

• params {Object} Request parameters.
• options {Object} Request options.
• Returns: {Promise} Promise array.

params is a history job information object, it can contain the following members:

• beginAt {String} Job creation time. Optional.
• endAt {String} Job end time. Optional.
• status {String} Job status. Optional.
• template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
• tags {Array} Job tags. Optional.

options is a history job extra information object, which is a parameter of pagination query, it can contain the following members:

• page {Number} Current page number.
• limit {Number} The quantity per page.

Get a history job object array of promise type, each job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.

# Example

const params = {
  beginAt: '1691569441556',
  endAt: '1692569441558',
  status: 'downloading',
  template: 'job_transport_upload',
  tags: []
}
const options = {
  page: 0,
  limit: 100
}

edger.job.history.query(params, options).then((payload) => {
  console.log("Jobs history list", payload )
}).catch(error => {
  console.error(error);
});

# async / await

async function query(params, options) {
  try {
    const payload = await edger.job.history.query(params, options);
    console.log("Jobs history list", payload )
  } catch (error) {
    console.error(error);
  }
}

# edger.job.history.count([params])

Retrieve the number of historical executions of job.

• params {Object} Request parameters. Optional.
• Returns: {Promise} Promise object.

params is a history job information object, it can contain the following members:

• beginAt {String} Job creation time. Optional.
• endAt {String} Job end time. Optional.
• status {String} Job status. Optional.
• template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
• tags {Array} Job tags. Optional.

Get a history job object of counting promise, the result object includes:

• count {Number} Historical number of jobs.

# Example

const params = {
  beginAt: '1691569441556',
  endAt: '1692569441558',
  status: 'downloading',
  template: 'job_transport_upload',
  tags: []
}

edger.job.history.count(params).then((payload) => {
  const { count } = payload
  console.log("Jobs history count:", count )
}).catch(error => {
  console.error(error);
});

# async / await

async function count(params) {
  try {
    const payload = await edger.job.history.count(params);
    const { count } = payload
    console.log("Jobs history count:", count )
  } catch (error) {
    console.error(error);
  }
}

# edger.job.history.delete(id)

Delete the historical execution records of job.

• id {String} Job unique identification.
• Returns: {Promise} Promise empty object.

# Example

const id = 'xxxx-xxxxxx-xxxxx-xxxxx'

edger.job.history.delete(id).then(() => {
  console.log("Job delete successfully")
}).catch(error => {
  console.error(error);
});

# async / await

async function delete(id) {
  try {
    await edger.job.history.delete(id);
  } catch (error) {
    console.error(error);
  }
}

# edger.job.history.deleteAll(params)

Delete all historical execution records of job.

• params {Object} Request parameters.
• Returns: {Promise} Promise empty object.

params is a history job information object, it can contain the following members:

• beginAt {String} Job creation time. Optional.
• endAt {String} Job end time. Optional.
• status {String} Job status. Optional.
• template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
• tags {Array} Job tags. Optional.

# Example

const params = {
  beginAt: '1691569441556',
  endAt: '1692569441558',
  status: 'error',
  template: 'job_transport_upload',
  tags: []
};

edger.job.history.deleteAll(params).then(() => {
  console.log("Jobs delete successfully");
}).catch(error => {
  console.error(error);
});

# async / await

async function deleteAll(params) {
  try {
    await edger.job.history.deleteAll(params);
  } catch (error) {
    console.error(error);
  }
}

# Events

The unified event listener provided by Web-SDK:

const listener = (payload) => {
  // Event handling...
}

// add listener
edger.job.addEventListener('some-event', listener);

// or 
// onAction() is an alias of addEventListener().
edger.job.onAction('some-event', listener);

// remove listener
edger.job.removeEventListener('some-event', listener);

// remove all listeners
edger.job.removeAllListeners();

# start

This event will be generated when the job starts.

• Returns: {Object} This job object.

Get a history job object of type promise, the job object includes:

• id {String} Job ID.
• status {String} Job status.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.

# Example

edger.job.addEventListener('start', (payload) => {
  const { id, status, createdAt, updatedAt, job } = payload;
  console.log('job start', id, status, createdAt, updatedAt, job);
});

# pause

This event will be generated when the job pauses.

• Returns: {Object} This job object.

Get a history job object of type promise, the job object includes:

• id {String} Job ID.
• status {String} Job status.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.

# Example

edger.job.addEventListener('pause', (payload) => {
  const { id, status, createdAt, updatedAt, job } = payload;
  console.log('job pause', id, status, createdAt, updatedAt, job);
});

# resume

This event will be generated when the job resumes.

• Returns: {Object} This job object.

Get a history job object of type promise, the job object includes:

• id {String} Job ID.
• status {String} Job status.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.

# Example

edger.job.addEventListener('resume', (payload) => {
  const { id, status, createdAt, updatedAt, job } = payload;
  console.log('job resume', id, status, createdAt, updatedAt, job);
});

# cancel

This event will be generated when the job cancels.

• Returns: {Object} This job object.

Get a history job object of type promise, the job object includes:

• id {String} Job ID.
• status {String} Job status.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.

# Example

edger.job.addEventListener('cancel', (payload) => {
  const { id, status, createdAt, updatedAt, job } = payload;
  console.log('job cancel', id, status, createdAt, updatedAt, job);
});

# done

This event will be generated when the job done.

• Returns: {Object} This job object.

Get a history job object of type promise, the job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.
• report {Object} The report object.
  • code {Number} Response code.
  • message {String} Code message.
  • seqId {Number} Sequence ID.
  • result {Object} Server response result.

# Example

edger.job.addEventListener('done', (payload) => {
  const { id, status, createdAt, updatedAt, job, report } = payload;
  console.log('job done', id, status, createdAt, updatedAt, job, report);
});

# error

This event will be generated when job error occurs.

• Returns: {Object} This job error object.

Get a history job object of promise type, the job object includes:

• id {String} Job ID.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.
• report {Object} The extra job object.

report is a history job information object, it can contain the following members:

• code {Number} Response code.
• message {String} Code message.
• seqId {Number} Sequence ID.
• result {Object} Server response result.

# Example

edger.job.addEventListener('error', (payload) => {
  const { id, job, report } = payload;
  console.log('job error:', id, job, report );
});

# progress

This event will be generated when job is in progress.

• Returns: {Object} This job progress object.

Get a history job object of promise type, the job object includes:

• id {String} Job ID.
• createdAt {Number} Job creation time.
• updatedAt {Number} Job update time.
• status {String} Job status.
• job {Object} The original job object (The details are consistent with the request parameters).
  • template {String} Job template name. Must be job_transport_upload_form or job_transport_download.
  • info {Object} Job execution information object.
  • option {Object} Extra information object for the job.
• report {Object} The extra job object.

report is a history job information object, it can contain the following members:

• currentSize {Number} The completed file size.
• totalSize {Number} Total file size.
• speed {Number} The download speed.
• seqId {Number} Sequence ID.
• uniqueId {Number} The file ID.

# Example

edger.job.addEventListener('progress', (payload) => {
  const { id, status, createdAt, updatedAt, job, report } = payload;
  console.log('job progress:', id, status, createdAt, updatedAt, job, report);
});