{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3a95593a",
   "metadata": {},
   "source": [
    "# Schedule and modify jobs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "256953d6",
   "metadata": {},
   "source": [
    "This example shows how to create a job request, schedule it for execution in the\n",
    "future, and modify the scheduled job before it completes.\n",
    "\n",
    "This example uses an Excel import job, but the functionality demonstrated here can be applied\n",
    "to text import and Excel export jobs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea18c4f",
   "metadata": {},
   "source": [
    "## Connect to Granta MI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4466ebe3",
   "metadata": {},
   "source": [
    "Import the ``Connection`` class and create the connection. For more information, see\n",
    "the [Connect and access the job queue](0_Getting_started.ipynb) example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43dc5216",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.jobqueue import Connection\n",
    "\n",
    "server_url = \"http://my_grantami_server/mi_servicelayer\"\n",
    "client = Connection(server_url).with_credentials(\"user_name\", \"password\").connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9298e27f",
   "metadata": {},
   "source": [
    "## Create an ``ExcelImportJobRequest`` object"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a02a543",
   "metadata": {},
   "source": [
    "This cell creates an Excel import job request and schedules it for execution tomorrow.\n",
    "This example does not contain a full description of the ``ExcelImportJobRequest`` object. For\n",
    "more information, see the [Create an Excel import job](1_Excel_import_job.ipynb) example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "347ff139",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "import pathlib\n",
    "\n",
    "try:\n",
    "    # Python 3.11+\n",
    "    from datetime import UTC as utc\n",
    "except ImportError:\n",
    "    # Python 3.9 and 3.10\n",
    "    from datetime import timezone\n",
    "\n",
    "    utc = timezone.utc\n",
    "\n",
    "from ansys.grantami.jobqueue import ExcelImportJobRequest\n",
    "\n",
    "tomorrow = datetime.datetime.now(utc) + datetime.timedelta(days=1)\n",
    "combined_excel_import_request = ExcelImportJobRequest(\n",
    "    name=\"Excel Import (combined template and data file)\",\n",
    "    description=\"An example excel import job\",\n",
    "    combined_files=[pathlib.Path(\"assets/combined_import_file.xlsx\")],\n",
    "    scheduled_execution_date=tomorrow,\n",
    ")\n",
    "\n",
    "combined_excel_import_request"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66ed182f",
   "metadata": {},
   "source": [
    "## Submit the job\n",
    "Next, submit the jobs to the server. There are two methods for submitting job\n",
    "requests:\n",
    "\n",
    "* ``create_job()``: Submit the job request to the server and immediately return an\n",
    "  ``AsyncJob`` object in the *pending* state.\n",
    "* ``create_job_and_wait()``: Submit the job request to the server and block until the job\n",
    "   either completes or fails. Return an ``AsyncJob`` object in the *succeeded* or *failed* state.\n",
    "\n",
    "Because you have configured the Excel job request object to execute tomorrow, you must use the\n",
    "``create_job()`` method. If you used the ``create_job_and_wait()`` method, it would block until\n",
    "the job completed, which means this script would take 24 hours to complete."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2d489d08",
   "metadata": {},
   "outputs": [],
   "source": [
    "deferred_job = client.create_job(combined_excel_import_request)\n",
    "deferred_job"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38c2e540",
   "metadata": {},
   "source": [
    "## List jobs\n",
    "Use the ``.jobs`` property to list the jobs on the server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9c16a053",
   "metadata": {},
   "outputs": [],
   "source": [
    "client.jobs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be78d545",
   "metadata": {},
   "source": [
    "Note that only jobs that you have access to are included in this property. Non-administrator users\n",
    "can only access and modify their own jobs. Administrator users can access and modify all jobs on the\n",
    "server."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5991deba",
   "metadata": {},
   "source": [
    "## Edit existing jobs\n",
    "You can edit the properties of a running or completed job with the associated ``AsyncJob``\n",
    "object. The following cell shows how to update the name and description of the job and to change the\n",
    "scheduled execution to occur immediately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "52773627",
   "metadata": {},
   "outputs": [],
   "source": [
    "deferred_job.update_name(\"Combined Excel Import (modified)\")\n",
    "deferred_job.update_description(\"A new description for a combined Excel import job\")\n",
    "\n",
    "now = datetime.datetime.now(utc)\n",
    "deferred_job.update_scheduled_execution_date_time(now)\n",
    "\n",
    "client.jobs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf28c5f8",
   "metadata": {},
   "source": [
    "## Retrieve long-running jobs\n",
    "If the job is expected to take a long time to complete, you can save the job ID to disk and\n",
    "use it with the ``client.get_job_by_id()`` method to check the status of the job later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebe8ac8f",
   "metadata": {},
   "outputs": [],
   "source": [
    "job_id = deferred_job.id\n",
    "retrieved_job = client.get_job_by_id(job_id)\n",
    "retrieved_job"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90265f3f",
   "metadata": {},
   "source": [
    "Wait for the pending job to complete."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29e32966",
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "\n",
    "from ansys.grantami.jobqueue import JobStatus\n",
    "\n",
    "while deferred_job.status not in [JobStatus.Succeeded, JobStatus.Failed]:\n",
    "    time.sleep(1)\n",
    "    deferred_job.update()\n",
    "\n",
    "deferred_job.status"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0508db43",
   "metadata": {},
   "source": [
    "## Access output files\n",
    "The job is now complete. You can access the files generated by the job in the same way as for\n",
    "jobs that execute immediately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8e53c9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "log_file_name = next(name for name in deferred_job.output_file_names if \"log\" in name)\n",
    "log_file_content = deferred_job.get_file_content(log_file_name)\n",
    "log_file_string = log_file_content.decode(\"utf-8\")\n",
    "print(f\"{log_file_name} (first 200 characters):\")\n",
    "print(f\"{log_file_string[:500]}...\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3845c2e7",
   "metadata": {},
   "source": [
    "## Delete a job\n",
    "You can delete jobs from the job queue using the ``.delete_jobs()`` method. This method\n",
    "accepts a list of jobs, which means that you can delete multiple jobs with a single request if required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43d0c2e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "client.delete_jobs([deferred_job])\n",
    "client.jobs"
   ]
  }
 ],
 "metadata": {
  "granta": {
   "clean_database": true
  },
  "jupytext": {
   "notebook_metadata_filter": "granta"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}