Create JOB and RPC Package

In this section you will learn how to create a DMS rpc and scheduled job starting from a template project. First of all download Samples from DMSContainer Repository

DMSContainer Repository Samples

Clone project dms_job_quickstart_full under dms_jobs_quickstart folder.

This project is going to be used as a template to create your job. Follow these steps:

  1. Open the cloned project in Delphi IDE

  2. Rename project as “dms_job_<yourjobname>”

  3. Rename unit Jobs.QuickStart3.RPC as “Job.<yourjobname>.rpc” and Jobs.QuickStart3.Job as “Job.<yourjobname>.job”

    rename job

Create Job Class

Rename Class TQuickStart3Job as “T<yourjobname>Job” rename job

Write your own job code in DoExecute method.

Job Configuration File

Optionally you can provide your job with custom configuration stored inside a config file. Job config can be stored in conf folder following this pattern:

job.<yourjobname>.config.json

It must contain a JSONObject with job configuration. Here it is, as example, jobemail configuration file:

{
  "max_retry_count": "5",
  "default_smtp_ssl_version":"TLSv1",
  "max_emails_count": 5
}

To access job configuration you can use TConfigurableJob jobs, JobConfig property:

lMaxRetries := lMaxRetries := JobConfig ['max_retry_count'].ToInteger;
if lMaxRetries < 1 then
begin
  raise EDMSConfigException.Create('max_retry_count', JobName);
end;

or using GetConfiguration method:

GetConfiguration(GetConfigFolder, JobName);

Create RPC Job Class

Rename Class TJobQuickStart3RPC as “T<yourjobname>RPC” rename job

Write the methods you want to expose. You can find the Echo function as example that can be delete.

JSONRPC allows you to call all public methods you define in your RPC Class

Special Folder Access

Inside your RPC Job class you can access special folders:

  • JobDataFolder: pointing to data folder under your DMS installation;
  • JobHomeFolder: pointing to DMS_HOME environment variable;
  • JobScriptsFolder: pointing to script folder under your DMS installation;
JSON Serialiazer

Inside your RPC Job class you can access special method to serialize/unserialize data:

 function GetSerializer: TMVCJsonDataObjectsSerializer;
 function JSONObjectAs<T: class, constructor>(const JSON: TJSONObject): T;
 procedure LoadJSONObjectAs<T: class, constructor>(const ObjectInstance: T;
      const JSON: TJSONObject);

Compile Package

Check whether DMS_HOME variable is setted and that points to your DMS installation, in tools\Options\Environment Variables: rename job

Build the package. You will find the newly created bpl under DMS installation in jobspackage folder as setted in Project Compiler Options: rename job

Setting up Configuration

Add Job configuration in jobsmanager.json file under Conf folder. Please change Jobname and jobclass with the right name:

  • jobname: it is a description name of your job
  • jobclass: it is the fully qualified job class name.
  • rpcuri: it is the path to your rpc resource
  • rpcclass: it is the fully qualified rpc class name.
{
  "enabled": true,
  "jobname": "your job name",
  "schedule": "* * * * * *",
  "jobtype":"class",
  "jobclass":"Jobs.<yourjobname>.Job.T<yourjobname>Job",
  "rpcclass":"Jobs.<yourrpcunitname>.RPC.<yourrpcclassname>",
  "rpcuri":"/<uripath>"  
}

Scheduling your job

To correctly schedule your job please follow configuration page the scheduling syntax paragraph.

Restart your DMS Service

Testing your RPC Job

To test your RPC job, you can create a JSONRPC request using TMVCJSONRPCExecutor class:

  private
    procedure ValidateCertificateEvent(
     const Sender: TObject; 
     const ARequest: TURLRequest;
         const Certificate: TCertificate; 
         var Accepted: Boolean);
  public
    { Public declarations }
  end;

implementation

uses
  System.NetEncoding, System.IOUtils, 
  MVCFramework.JSONRPC, MVCFramework.JSONRPC.Client;

procedure TMainForm.btnRequestClic(Sender: TObject);
var
  lReq: IJSONRPCRequest;
  lResp: IJSONRPCResponse;
  lRPCExecutor: IMVCJSONRPCExecutor;
begin
  lRPCExecutor := TMVCJSONRPCExecutor.Create('https://localhost/<yourrpcclassuri>');
  //define ValidateCertificateEvent to escape certificate validation or you
  lRPCExecutor.SetOnValidateServerCertificate(ValidateCertificateEvent);
  lReq := TJSONRPCRequest.Create(1234, '<yourmethodname>');
  lReq.Params.Add(<paramvalue>);  

  lResp := lRPCExecutor.ExecuteRequest(lReq);
  showmessage(lResp.Result.AsString); //test result if you method returns one
end;

procedure TMainForm.ValidateCertificateEvent(const Sender: TObject;
  const ARequest: TURLRequest; const Certificate: TCertificate;
  var Accepted: Boolean);
begin
  Accepted := True; // do not check certificate
end;

otherwise you can use any RESTClient and create a request:

  • url: ‘https://localhost/<yourrpcclassuri>:

  • http verb: POST

  • body:

    {"jsonrpc": "2.0", "method": "yourrpcmethod", "params": [<array of params>], "id": 1}

See also