# Run & Monitor Jobs in Oracle ARCS from Oracle APEX # Introduction In my [previous post](https://blog.cloudnueva.com/arcs-file-integration-apex), 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](https://docs.oracle.com/en/cloud/saas/account-reconcile-cloud/adarc/get_start_learn_about_trans_match_100x6cae3ed7.html), 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](https://blog.cloudnueva.com/arcs-file-integration-apex) in this series for details on Authentication for ARCS REST Services, as well as how to get the ``, which I refer to throughout this post. # Documentation Links The ARCS documentation has a generic section, [Execute a Job in Account Reconciliation](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_execute_a_job.html), describing how to start jobs. It also has sections for starting specific Transaction Matching jobs: * [Import Pre-Mapped Transactions (Transaction Matching)](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_rest_import_tm_premapped_transactions.html) * [Run Auto Match (Transaction Matching)](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_rest_tm_automatch.html) * [Purge Transactions (Transaction Matching)](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_rest_tm_purge_transactions.html) Link to documentation for the [Retrieve Job Status API](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_get_job_status.html). 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)](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_rest_import_tm_premapped_transactions.html) 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 ![Oracle ARCS Start a Job Postman](https://cdn.hashnode.com/res/hashnode/image/upload/v1671980368247/2b08b05b-5377-4d4e-bf59-20a756c78c62.png align="center") * Method is `POST` * URL append `arm/rest/v1/jobs` to the `` * Content-Type is `application/json` ![Oracle ARCS Start a Job Postman](https://cdn.hashnode.com/res/hashnode/image/upload/v1671980570742/6853d215-85e4-4478-9552-b6688bac43e8.png align="center") ### 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: ![Oracle ARCS Start Job ARCS Job Queue](https://cdn.hashnode.com/res/hashnode/image/upload/v1672070591435/d7ef17e7-1764-44b2-a20e-4eec7b1cf8de.png align="center") ## 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: %[https://gist.github.com/jon-dixon/19223787c214eee5c89f08dcc38ec2f4] Here is a PL/SQL block showing how we can start the [Import Transactions](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_rest_import_tm_premapped_transactions.html) job from a PL/SQL block: %[https://gist.github.com/jon-dixon/4f6fc51b6d1036a688a2c331c475b499] 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](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_execute_a_job.html) REST API returns a link to the [Retrieve Job Status REST API](https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/arcs_get_job_status.html) for the submitted job. This makes things easy; all we need to do is send a GET request to the returned URL. ## From Postman ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1672071448695/6f635b0f-bad0-40b3-8d11-1fee8a97df4c.png align="center") * Method is `GET` * URL append `arm/rest/v1/jobs/` to the `` * Content-Type is `application/json` **Example Response** ```json { "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:///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. ![Oracle ARCS Get Job Status Postman Log](https://cdn.hashnode.com/res/hashnode/image/upload/v1672071700031/62efbc16-dc3c-4d6c-a9e0-88a238e30a9c.png align="center") Example of Downloaded Log File: ![Oracle ARCS Get Job Status Postman Log File Downloaded](https://cdn.hashnode.com/res/hashnode/image/upload/v1672071799649/1cb430e5-bb38-4599-be60-da7c4f63453e.png align="center") If the job is still running when you check its status, then you will see a response like this: ```json { "type": "TM", "items": [-1], "error": null, "link": null, "status": -1, "details": "Job Still Running..", "links": [{ "rel": "self", "href": "https:///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: %[https://gist.github.com/jon-dixon/465345b2c81bedd42e6f0d5961040f94] Here is a PL/SQL block showing how you can retrieve the status and the log file for a given Job URL: %[https://gist.github.com/jon-dixon/13bb0feb73141b5c838ac9f836d4484b] # 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: %[https://gist.github.com/jon-dixon/a440fca639ea4cef6e43d9127405a191] # 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](https://blog.cloudnueva.com/series/arcs)