Introduction

In my previous post, I showed you how to send files to the ARCS file system using Oracle APEX. This is the first step in most inbound integrations to ARCS. In this post, I will show you how to start an ARCS job from APEX and monitor its status. This is often the second step when integrating data into ARCS. For example, when performing Transaction Matching, you must complete the following steps:

1. Send CSV file(s) to the ARCS file system

2. Run the Import Transactions job to upload files into tables

3. Run the Auto Match job to perform transaction matching on the imported data

Background

Please refer to the first post in this series for details on Authentication for ARCS REST Services, as well as how to get the <BaseURL>, which I refer to throughout this post.

Documentation Links

The ARCS documentation has a generic section, Execute a Job in Account Reconciliation, describing how to start jobs. It also has sections for starting specific Transaction Matching jobs:

• Import Pre-Mapped Transactions (Transaction Matching)

• Run Auto Match (Transaction Matching)

• Purge Transactions (Transaction Matching)

Link to documentation for the Retrieve Job Status API. This API can be used to check if a job has finished running and what status is completed.

Starting a Job

I will use the example of starting the Import Pre-Mapped Transactions (Transaction Matching) job. One thing to note is that ARCS jobs are asynchronous, which means that they run independently of the process that started them. The REST API I describe in this section starts the job; you will need to use the REST API described in the next section to check on the status of the job.

From Postman

• Method is POST

• URL append arm/rest/v1/jobs to the <BaseURL>

• Content-Type is application/json

Payload

The payload for this job consists of a JSON object:

• jobName - The name of the job to run

• parameters - a JSON object containing the parameters for the job

Response

The key fields in the response include the following:

• status Indicates the status of the job submission -1 indicates the job was submitted successfully, and any other value indicates an error.

• details shows details if the status is not -1

• links An array of links. There will only be one item in the array, which contains a link to the status API for the job that was started.

If we then log in to ARCS, we can see the job in the queue:

From APEX

I have written a helper procedure start_job to start a job and return the URL to the job status REST API. The code includes comments to explain what is going on:

Here is a PL/SQL block showing how we can start the Import Transactions job from a PL/SQL block:

As with a submission from Postman, you can see the job from the ARCS UI or follow the link in the response.

Checking Job Status

After starting a job, we typically want to check its status to ensure it is completed successfully. In the previous section, we saw that the jobs REST API returns a link to the Retrieve Job Status REST API for the submitted job. This makes things easy; all we need to do is send a GET request to the returned URL.

From Postman

• Method is GET

• URL append arm/rest/v1/jobs/<jobNumber> to the <BaseURL>

• Content-Type is application/json

Example Response

{
  "type": "TM",
  "items": [
    1
  ],
  "error": null,
  "link": null,
  "status": 1,
  "details": "Job failed. Job ID: 100000003537016 Log file: 100000003537016_AP.log\n\r\nError at line no 1 : Import transaction file does not have headers.\r\n\r\nStatus                 : Import file does not have any records to process.\r\nTotal Record Processed : 0\r\nTotal Records saved    : 0\r\nTotal time taken       : 00 Minute(s) and 00 Second(s)",
  "links": [
    {
      "rel": "self",
      "href": "https://<baseURL>/arm/rest//v1/jobs/100000003537016",
      "action": "GET",
      "data": null
    }
  ]
}

In the example response, you can see that the job was completed in error (status = 1). The details field contains the log file from the job. You can also see the log file from the ARCS UI by clicking on the 'User.log' link related to the job.

Example of Downloaded Log File:

If the job is still running when you check its status, then you will see a response like this:

{
    "type": "TM",
    "items": [-1],
    "error": null,
    "link": null,
    "status": -1,
    "details": "Job Still Running..",
    "links": [{
        "rel": "self",
        "href": "https://<baseURL>/arm/rest//v1/jobs/100000003540032",
        "action": "GET",
        "data": null
    }]
}

From APEX

I have written a helper procedure job_status to return the status for a job. The code includes comments to explain what is going on:

Here is a PL/SQL block showing how you can retrieve the status and the log file for a given Job URL:

Bringing it all Together

In real life, we would typically want to start the job, wait for it to complete, and then take action based on the completion status. Here is an example PL/SQL block, which does just that:

Conclusion

In this post, I demonstrated how to start an ARCS job and retrieve the status of the job once it has been completed. This pattern is worth understanding, as it is used throughout Oracle SaaS products. In my final post of the ARCS series, I will show you how you can export data from ARCS via REST APIs.

🔗 Read More

• Integrating with Oracle ARCS using APEX