iSchedule

iSchedule allows you to schedule iImport Cloud or iUpdate Cloud tasks. Tasks can be set to run off hours (after your users are logged off) and/or on a recurring basis. iSchedule can be run daily, monthly, or hourly.  

There are many possible ways to use iSchedule, here are just a few of them:

  • Schedule an iUpdate Task to run on a recurring basis
  • Schedule an iUpdate or iImport task to run after hours

Creating a Scheduled Task 

Once you are on the Mapping step. After completing mappings and selecting your options, select Schedule as Task.

Create/Edit Task Page

After clicking the Schedule as Task button or clicking the edit button on an existing task, you be on the Edit Task page.

  1. Create a name for your scheduled task.
  2. Add a helpful description for your task.
  3. Determine the number of times a job can fail before being automatically disabled.
  4. The Crontab Schedule (UTC) will allow you to schedule a recurring or a one-time task.
  5. Disable / Enable your scheduled task 
    1. Click on the Schedule Builder button on the right. This will pop up a dialog box like the one below.
    2. Click on Recurring to schedule a task that you want to run on a scheduled basis over and over
    3. Click on One-Time to schedule a task that you want to run one time only.

      4. Note: Times are in UTC time.

    4. Once you have your schedule set, click Save.

The task appears in the Task List. From here, view  the listing.

You also have the ability to sort on the column headers. Sort by Name, Last Run, Next Run, and more.

You can also edit the task, edit the mappings, delete the task, or run the task now. 

Disable an Active Scheduled Task

To disable an active scheduled task:

  1. Log into your iDMS dashboard.
  2. Enter iSchedule and locate the job that you would like to disable.
  3. Once you've found it, choose the yellow Edit button under the Actions row.
  4. You should now be on the Edit Task page for your job. Make sure to disable the 'Is Enabled' option.
  5. Save.

Using Webhooks and HTTP Triggers

iSchedule makes it possible to remotely trigger your task.

Webhook information

To view webhook / trigger information for a task, click the icon next to a task. Webhook information can be found under the POST Webhook URLs header.

Standard (Fire-and-Forget) URL

Note: This is the URL with original, unchanged behavior from previous versions of iDMS.

This webhook type will start the corresponding iUpdate task. It will return an error only if there was an issue initializing / starting the job.

This webhook type will not:

  • Wait for the iUpdate job to finish.
  • Tell you if the iUpdate job succeeded or failed (at the end).
  • Tell you how many records it retrieved and/or processed.

Example

The following are examples:

Power Automate

Use the HTTP action:

cURL

Copy 
curl -X POST https://iimport.cloud.csiinc.com/task/execute/00000000-0000-0000-0000-000000000000

Raw HTTP

Copy 
POST /task/execute/00000000-0000-0000-0000-000000000000 HTTP/1.1
Host: iimport.cloud.csiinc.com
User-Agent: example-documentation/1.0
Content-Length: 0

jQuery

The following jQuery is written to execute the task on page load:

Copy 
<script>jQuery(document).ready(function() {
    const runTask = async () => {
        const iMISID = JSON.parse(document.getElementById("__ClientContext").value).selectedPartyId;
        const res = await fetch("https://iimport.cloud.csiinc.com/task/execute/555e1a89-5d7d-4daf-ae0e-sampleGUID", {
            method: "POST",
            body: JSON.stringify({
                QueryParameters: {
                    ID: iMISID,
                },
            }),
            headers: {
                "Content-type": "application/json;",
            },
        });
        const data = await res.json();
        console.log(data);
    };
    runTask();
});
</script>

Asynchronous Polling URL

This is the URL with newer, "wait for completion" functionality in iDMS which supports iUpdate job chaining and has better support for external tooling such as Microsoft Power Automate.

This webhook type will start the corresponding iUpdate task and return a special HTTP status code that indicates that the job has started, and where you can poll to retrieve the job status. This endpoint will also notify you when the job has been completed.

This webhook type will not:

  • Wait for the job to complete before returning the HTTP response. (Jobs can take much longer than the maximum HTTP timeout value.)

HTTP Polling Overview

To use the polling endpoint, you must have an application or tool that is compatible with the Asynchronous Request-Response Pattern, or you can write your own custom script/application that implements this pattern.

The asynchronous polling pattern can be summarized as:

  • You make a standard webhook POST call to the polling endpoint, the same as other webhooks
  • You will receive a 202 Accepted response, with two important headers: Location and Retry-After.
    • Location specifies where you need to poll for the job status
    • Retry-After specifies how often you should poll
  • You issue a GET request to the polling endpoint. You will receive one of two possible responses back:
    • 202 Accepted - Indicates that the job has not yet completed.
      • The JSON body of this response will contain the job status (typically "in progress") as well as the percentage completion and some other useful status values.
      • Your application should re-issue this same GET request after the specified "Retry-After" interval (typically 30 seconds).
    • 200 OK - Indicates the job has completed.
      • The JSON body indicates if the job was successful or not, and contains statistics about the number of records processed, etc.
      • Your application should stop polling after receiving this response. Subsequent requests to this endpoint will always return the same JSON response.

Examples

The following are examples:

Power Automate

  1. Use the HTTP action:

  2. Click the menu and select Settings.

  3. Ensure that Asynchronous Pattern is on.

Now, Power Automate will not continue on to the next action until the iDMS job is completed. It is therefore possible to chain multiple iDMS jobs in sequence using this method with Power Automate.

When you run your workflow action(s), note that Power Automate does not display the intermediate polling steps (the "202 Accepted" polling requests). The action will remain in an "executing" or "waiting" status until the iDMS job is completed. Polling is handled internally by Power Automate.

The following screenshot shows that the task took 11 minutes to process. The Power Automate workflow continued to the next step only after the iDMS job was completed.

C#

Copy 
using System;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
 var httpClient = new HttpClient();
 // Start the job
var jobStartResponse = await httpClient.PostAsync("https://iimport.cloud.csiinc.com/task/executepolling/00000000-0000-0000-0000-000000000000", null);
 // Get the polling URL and polling interval from the response headers
var pollingUrl = jobStartResponse.Headers.Location;
var pollingInterval = jobStartResponse.Headers.RetryAfter.Delta ?? TimeSpan.FromSeconds(30);
 HttpResponseMessage lastResponse = default;
 do
{
    // If we are still in polling mode, then wait
    if (lastResponse is null or { StatusCode: HttpStatusCode.Accepted })
    {
        await Task.Delay(pollingInterval);
        // or Thread.Sleep()
    }
         // Issue a request to fetch the latest status
    lastResponse = await httpClient.GetAsync(pollingUrl);
     // Loop while we are still receiving 202 Accepted responses
} while (lastResponse.StatusCode == HttpStatusCode.Accepted);
  var jsonJobStatus = await lastResponse.Content.ReadAsStringAsync();
 // Deserialize or read properties from the JSON response...

cURL

Copy 
curl -X POST https://iimport.cloud.csiinc.com/task/executepolling/00000000-0000-0000-0000-000000000000
# Receive 202 Accepted
curl https://iimport.cloud.csiinc.com/task/executepolling/00000000-0000-0000-0000-000000000000/00000/status
# If 202 Accepted: Repeat at regular intervals (30 seconds)
# If 200 OK: Read job status and continue

RAW HTTP

Copy 
POST /task/executepolling/00000000-0000-0000-0000-000000000000 HTTP/1.1
Host: iimport.cloud.csiinc.com
User-Agent: example-documentation/1.0
Content-Length: 0
202 Accepted
Location: /task/executepolling/00000000-0000-0000-0000-000000000000/00000/status
Retry-After: 30
Content-Type: application/json
{ ... }
GET /task/executepolling/00000000-0000-0000-0000-000000000000/00000/status HTTP/1.1
Host: iimport.cloud.csiinc.com
User-Agent: example-documentation/1.0
Content-Length: 0
202 Accepted
Location: /task/executepolling/00000000-0000-0000-0000-000000000000/00000/status
Retry-After: 30
Content-Type: application/json
{ ... }
GET /task/executepolling/00000000-0000-0000-0000-000000000000/00000/status HTTP/1.1
Host: iimport.cloud.csiinc.com
User-Agent: example-documentation/1.0
Content-Length: 0
200 OK
Content-Type: application/json
{ ... }

Passing IQA Query Parameters with Webhooks

It is possible to pass IQA parameters (prompts marked "Optional" or "Required" in iMIS) into a webhook request (standard or polling) and have those parameters apply to the IQA dynamically at runtime.

To view the webhook body template, and see the list of parameter names that are able to be passed into the webhook, click the icon next to a task, and expand the collapsible section titled Query Parameters Overload on POST Request.

You'll see a preview window containing a JSON object template that you can use to pass parameters in.

This JSON object should be included in your initial webhook POST body. 

IQA Query Parameter Key Names

The names of the parameters are derived from the column name from the Business Object (or source IQA) of the corresponding filter row in the IQA. 

If you have filter lines for CsContact.FirstName, CsContact.LastName, and CsContact.Email, then your query parameter keys JSON object would look like this:

Copy 
{
  "QueryParameters": {
    "FirstName": "",
    "LastName": "", 
    "Email": "", 
  }
}

Note: Passing in a null or empty string will cause iDMS to use the default parameter provided in the iDMS interface when the task was set up, or, the default parameter in the IQA if the iDMS task also does not have a value.

Important! It is not currently possible to have two filter rows in an IQA that share the same column name. For example, if you add CsContact1 and CsContact2 (linked via the Company ID relationship), it would not be possible to provide parameter values for both the parent company "ImisId" and individual child "ImisId" filters at the same time, since the column name is the same.