Skip to main content

ExecuteCommonProgram Async Job (Create, Get, Update)

This document explains how to create, track, and update an ExecuteCommonProgram async job using the Async Job service APIs and the Program Service method.

It provides an end-to-end reference covering:

  • Creating async jobs
  • Tracking job execution
  • Updating job metadata
  • Polling job status
  • Complete working examples

Reference​

Create Task<Guid> CreateAsyncJobAsync(Prorigo.Protrak.API.Contracts.AsyncJob job)
Create Task<Guid> ExecuteCommonProgramAsAsyncJobAsync(string programName, params object[] arguments)
Get Task<Prorigo.Protrak.API.Contracts.AsyncJob> GetAsyncJobAsync(Guid jobId)
Update Task UpdateAsyncJobAsync(Guid jobId)

Parameters​

Async Job Creation​

AsyncJob​

  • Prorigo.Protrak.API.Contracts.AsyncJob job\

    • Must be Prorigo.Protrak.API.Contracts.AsyncJob.

  • Prorigo.Protrak.API.Contracts.ProgramExecutionInfo ProgramExecutionInfo

    • string ProgramName
      Name of the Common Program to execute.
    • object[] Arguments
      Input arguments passed to the Common Program.

Returns​

Create Methods​

  • Guid
    • Unique Async Job Identifier

Get Method​

  • AsyncJob
    • Guid Id
    • AsyncJobType Type
    • AsyncJobStatus Status
    • DateTime Created
    • DateTime? CompletedDate
    • string ErrorMessage
    • ProgramExecutionInfo ProgramExecutionInfo
    • User Creator
    • bool IsRead

Usage​

Create ExecuteCommonProgram Async Job​

Using AsyncJobService​

public IAsyncJobService AsyncJobService { get; set; }

var job = new AsyncJob
{
    Type = Prorigo.Protrak.API.Contracts.Enums.AsyncJobType.ExecuteCommonProgram,
    ProgramExecutionInfo = new Prorigo.Protrak.API.Contracts.ProgramExecutionInfo
    {
        ProgramName = "DataMigrationProgram",
        Arguments = new object[] { "sourceId", "targetId", 100 }
    }
};

Guid asyncJobId = await AsyncJobService.CreateAsyncJobAsync(job);

Using ProgramService​

public IProgramService ProgramService { get; set; }

Guid asyncJobId = await ProgramService.ExecuteCommonProgramAsAsyncJobAsync(
    "DataMigrationProgram",
    "sourceId", "targetId", 100
);

Get Async Job Metadata and Status​

public IAsyncJobService AsyncJobService { get; set; }

var job = await AsyncJobService.GetAsyncJobAsync(jobId);

Common Fields​

  • Id
  • Type
  • Status
  • Created
  • CompletedDate
  • ErrorMessage
  • ProgramExecutionInfo
  • Creator
  • IsRead

Sample GetAsyncJob Response (Generic Example)​

{
  "id": "<AsyncJobId-Guid>",
  "type": "ExecuteCommonProgram",
  "status": "<Completed | Failed | Running | Abandoned>",
  "creator": {
    "userId": "<UserId-Guid>",
    "userName": "<CreatorName>",
    "userEmail": "<CreatorEmail>"
  },
  "created": "<UTC Timestamp>",
  "completedDate": "<UTC Timestamp | null if not completed>",
  "isRead": false,
  "bulkOperationType": 0,
  "programExecutionInfo": {
    "programName": "<CommonProgramName>",
    "arguments": ["<Argument1>", "<Argument2>", "<Argument3>"],
    "result": ["<ProgramResult>"]
  }
}

Field Description​

FieldDescription
idUnique identifier of the async job
typeType of async job being executed
statusCurrent execution state of the job
creatorDetails of the user who created the job
createdJob creation timestamp
completedDateJob completion timestamp
isReadIndicates whether the job has been marked as read
bulkOperationTypeReserved field for bulk job operations
programExecutionInfo.programNameName of the executed Common Program
programExecutionInfo.argumentsInput parameters passed to the program
programExecutionInfo.resultOutput returned by the program

Possible Status Values​

InProgress
Completed
Failed
Abandoned

Notes​

  • completedDate is null until job execution finishes.
  • result is available only when status = Completed.
  • errorMessage will be present if status = Failed.

Update Async Job Metadata​

public IAsyncJobService AsyncJobService { get; set; }

await AsyncJobService.UpdateAsyncJobAsync(jobId);

End-to-End Example (Create → Poll for Result)​

Create Async Job to Execute Common Program​

example using AsyncJobService.CreateAsyncJobAsync:

using System;
using System.Threading.Tasks;
using Prorigo.Protrak.Programs;
using Prorigo.Protrak.API.Services;
using Prorigo.Protrak.API.Contracts;

namespace Prorigo.CustomPrograms
{
    public class CreateAsyncJobProgram : ICommonProgramAsync
    {
        public IAsyncJobService AsyncJobService { get; set; }

        public async Task<object> RunAsync(params object[] arguments)
        {
            var job = new AsyncJob
            {
                Type = AsyncJobType.ExecuteCommonProgram,
                ProgramExecutionInfo = new ProgramExecutionInfo
                {
                    ProgramName = "DataMigrationProgram",
                    Arguments = new object[] { "sourceId", "targetId", 100 }
                }
            };

            Guid jobId = await AsyncJobService.CreateAsyncJobAsync(job);
            return new object[] { jobId };
        }
    }
}

example using ProgramService.ExecuteCommonProgramAsAsyncJobAsync:

using System;
using System.Threading.Tasks;
using Prorigo.Protrak.Programs;
using Prorigo.Protrak.API.Services;
using Prorigo.Protrak.API.Contracts;

namespace Prorigo.CustomPrograms
{
    public class CreateAsyncJobProgram : ICommonProgramAsync
    {
        public IProgramService ProgramService { get; set; }

        public async Task<object> RunAsync(params object[] arguments)
        {
            Guid jobId = await ProgramService.ExecuteCommonProgramAsAsyncJobAsync(
                "DataMigrationProgram",
                "sourceId", "targetId", 100
            );
            return new object[] { jobId };
        }
    }
}

Poll Async Job​

using Prorigo.Protrak.API.Contracts;
using Prorigo.Protrak.API.Contracts.Integration;
using Prorigo.Protrak.API.Services;
using Prorigo.Protrak.Programs;
using System;
using System.Threading.Tasks;

namespace Prorigo.CustomPrograms
{
public class PollAsyncCommonProgramForResult : ICommonProgramAsync
{
    public IAsyncJobService AsyncJobService { get; set; }

    public async Task<object> RunAsync(params object[] arguments)
    {
        if (arguments.Length == 0 || !(arguments[0] is Guid))
            return new object[] { "Error", "AsyncJobId is required." };

        return await WaitForJob((Guid)arguments[0]);
    }

    private async Task<object[]> WaitForJob(Guid jobId)
    {
        while (true)
        {
            var job = await AsyncJobService.GetAsyncJobAsync(jobId);

            switch (job.Status)
            {
                case AsyncJobStatus.Completed:
                    return new object[] { job.Status, job.ProgramExecutionInfo };

                case AsyncJobStatus.Failed:
                    return new object[] { job.Status, job.ErrorMessage };

                case AsyncJobStatus.Abandoned:
                    return new object[] { job.Status };
            }

            await Task.Delay(2000);
        }
    }
}

Troubleshooting​

  • Verify program name and arguments during job creation.
  • Inspect ErrorMessage if job execution fails.
  • Ensure background worker service and message queue are operational.
  • Common issues includes program not found, not published.

Best Practices​

  • Do not poll Async Jobs within the same request that creates them. (Because the job won't start/create until the request completes, so polling would be ineffective.)
  • Always log the Async Job Id.
  • Prefer ProgramService for simplified creation.
  • Monitor jobs using background services or client monitoring.
  • Keep the arguments and result size reasonable to avoid performance issues.