LogJobFromJobTemplate

Endpoint

POST - /jobs/LogJobFromJobTemplate

Overview

The LogJobFromJobTemplate endpoint is used to log a new job from an existing Job Template. Before this endpoint can be used, the Job Template must already exist and be fully configured and ready for use. Job Template administration is performed via the Desktop version of HelpMaster.

When a new job is logged using this API, all aspects of the Job Template configuration will be applied. This includes the Action Template for job assignment, as well as any Email Templates that are linked to the Action Template. OnCreate workflow will also be executed if this is configured for the Job Template. If any component of the Job Template has not been configured correctly, the log new job web API call will fail, and return an error code and/or validation message.

Note! OnCreate workflow occurs after a job is fully logged and all aspects of the Action Template and associated Email Templates have completed, so if the OnCreate workflow fails for whatever reason, this means that the job has already been fully logged. Any workflow issues will then need to be addressed by the HelpMaster administrator.

A good test of whether a job template can be used with this web API is to log a job that uses that template via the Request Catalog system via the Web Portal. If it works there, it will work here.

Parameters

JobTemplatePKID

The PKID of a existing Job Template. Use the HelpMaster Desktop edition to open a Job Template and check the “Properties” tab to determine the PKID. See picture below.

Summary

The Job Summary. This value will overwrite any value that is in the Job Template. To use the value in the job Template, leave this blank.

Details

The Job Details. This value will overwrite any value that is in the Job Template. To use the value in the job Template, leave this blank.

PrimaryClientPKID

The PKID of the primary client (can be a client or staff) for the newly logged job. This value will overwrite any value that is in the Job Template. To use the value in the job Template, leave this blank.

ControlSets

The Control Set definition to set the values for any Control Sets that are linked to the Job Template. Options include:

1. Leave blank to log the job without any values for Control Sets (may not be possible if some Control Set fields are marked as “mandatory”)
2. Provide “lite” details for a Control Set (just the field GUID + value)
3. Provide “full” details for a Control Set (the full Control Set definition)

In order to get the JSON definition of a Control Set that can be used for this parameter, use the /docs/extending/web-api/jobs/getcontrosetlitetemplateforlogjob/ WebAPI

Important! When using Control Set entity pickers (Clients, Sites, Assets), AND you are using a custom stored procedure to populate the values, please ensure that the value you provide to the WebAPI is the entity ID as displayed in their corresponding detail screen (ClientID, AssetID, Site) - NOT the display value that may have been generated by the custom stored procedure.

Examples

Log a job from a template without any Control Set information.

{
  "jobTemplatePKID": 7,
  "summary": "Printer #3 has gone offline",
  "details": "Printer #3 Hardware fault code: XYZZY",
  "primaryClientPKID":88
}

Log a job from a template with Control Set information.

{
    "jobTemplatePKID": 7,
    "summary": "Printer #3 has gone offline",
    "details": "Printer #3 Hardware fault code: XYZZY",
    "primaryClientPKID": 88,
    "controlSets": [
        {
            "controlSetPKID": 8,
            "controls": [
                {
                    "guid": "0d282bda-02df-4ca8-a54c-4d0370b0e156",
                    "stringValue": "Laser"
                },
                {
                    "guid": "711fb656-29c8-424b-9b77-5760ac94211b",
                    "stringValue": "LP500.19"
                },
                {
                    "guid": "416e06a1-256a-4318-84ac-270644f887e1",
                    "stringValue": "XYZZY"
                }
            ]
        }
    ]
}

Example specifying values for 2 different Control Sets.

{
    "jobTemplatePKID": 7,
    "summary": "Printer #3 has gone offline",
    "details": "Printer #3 Hardware fault code: XYZZY",
    "primaryClientPKID": 88,
    "controlSets": [
        {
            "controlSetPKID": 8,
            "controls": [
                {
                    "guid": "0d282bda-02df-4ca8-a54c-4d0370b0e156",
                    "stringValue": "Laser"
                },
                {
                    "guid": "711fb656-29c8-424b-9b77-5760ac94211b",
                    "stringValue": "LP500.19"
                },
                {
                    "guid": "416e06a1-256a-4318-84ac-270644f887e1",
                    "stringValue": "XYZZY"
                }
            ]
        },
        {
            "controlSetPKID": 39,
            "controls": [
                {
                    "guid": "9fb6a9d5-7eae-499e-8448-46b735fba675",
                    "stringValue": "This is a string value!"
                }
            ]
        }
    ]
}

See also

GetControlSetLiteTemplateForLogJob

Request Catalog