(v1) .Custom API v2.1.4.7

Basics

This feature allows the admin to define customized API routines. These routines can be executed via an API call using the Custom API identifier.

This Grid allows Users to add custom API calls.

Identifier: This is the unique identifier for the specific API logic. This identifier is used to invoke this Custom Logic with an API Call.
Description: A description field to provide additional information as to the purpose of the API logic.
Logic Entry field: All of the logic for the particular API call.

Prerequisites

This feature is intended for Administrators and an understanding of PHP language and syntax is required. You must also be aware of language compatibility for the version of PHP installed on the webserver. For logic that requires querying other data, an understanding of SQL is necessary, particularly variants specific to your database platform.

Usage

In a typical API routine, incoming request data is processed and an outgoing response is built.

Scope

API routines are written and executed within a subset of PHP syntax and at run time they have scope access to two arrays of data $request and $response. For security purposes, only a subset of PHP functions have been whitelisted.

$request

A key/value paired array of the data that is POSTED to the API REST request. The contents of this request will vary depending on how and what is making the API request. There is no need to decode the $request data.

$response

A key/value paired array of the data that should be returned in the API REST response.

Example

Using cURL, we invoke a Custom API called hello-world:

curl -X POST -d '{"foo":"bar"}' http://DOMAIN/api/API_KEY/hello-world.json -H Content-Type:application/json

The .json extension requests data returned JSON encoded
The Content-Type header directive for "application/json" specifies the incoming request data is JSON encoded

Within the Custom API logic, $request would contain the decoded request data:

array(
  "foo" => "bar"
)

The response can be built by assigning data to $response.

$response["hello"] = "world";

The given cURL request will return a JSON formatted response:

{ "hello" : "world" }

Syntax

Custom API shares a set of common syntax and available functions with the other types of Custom Logic.

call

Additionally, the Custom API can invoke the Write methods for other API types by using the call function. This function allows passing data from the Custom API to the other APIs if the given API key has sufficient write permission. This feature allows you to reformat the incoming API data - perform data validation and lookup and then handoff the properly formatted data to write Services, Equipment, or Service Desk.

array $this->call ( string $method, array $bind_params);

Parameters

$method The callable method name. The available callable methods: saveCable (2.1.4.5), saveEquipment (2.1.4.6), saveGla (2.1.4.5), saveService (2.1.4.6), saveServiceDesk $params An array of key payload data that is passed to the other API calling function.

Return Values

The function returns a result array containing 'data' which specifies the outcome of the call. For a successful call to saveServiceDesk, this array contain the Service Desk item/action that was created.

Example

In this example, the $payload array contains all the parameters required to create a Service Order and Action

    $result = $this->call("saveServiceDesk", $payload);
    $response["servicedesk_number"] = $result["data"];

Invoking Custom API

Read more about Making a Request for APIs and reading into the Custom API.

Example

This Custom API script was written to process incoming API calls from Slack (a team chat program we use internally at PCR).

<?php
/**
 * Type: Custom Logic
 * Identifier: helpdesk
 */

// The incoming payload from Slack is JSON encoded so we need to decode it...  
// Usually there is no need to decode the request parameter.  However, Slack 
// sends the "payload" parameter as a JSON encoded string
$payload = json_decode($request["payload"], true);

$user = $payload["user"]["name"];
$callbackId = explode("-",$payload["callback_id"]);
$iconUrl = "https://www.iconexperience.com/_img/v_collection_png/24x24/plain/";
$icon = "error.png";

// find the Contact for this User - using the query function is best with
// bound parameters instead of placing them directly into the query string.
// This protects the database against injection threats
$contacts = $this->query(
    "SELECT RECID FROM CONTACTS C
    LEFT JOIN V_UDF UDF ON UDF.VALUE_TABLE_NAME = 'CONTACTS' AND C.RECID = VALUE_TABLE_RECID
    WHERE UDF.VALUE = :slack_user",
    [":slack_user" => "@".$user]
);

if(!empty($contacts)){
    // the query function always returns an array
    // of rows so we need to look at the first index
    $contact = $contacts[0];

$incidents = $this->query(
        "SELECT SD.*, D.CODE, L.VALUE AS STATUS
        FROM SERVICE_DESK SD
        LEFT JOIN DEPT_HIERARCHY D ON SD.D_OWNER_DEPT_HIERARCHY_RECID = D.RECID
        LEFT JOIN LISTS L ON SD.SD_STATUS_LISTS_RECID = L.RECID
        WHERE SD_NUMBER = :incident",
        [":incident" => $callbackId[0]]
    );

if(!empty($incidents)){
        $incident = $incidents[0];

$workflow = $this->query(
            "SELECT SDWF.*, CONCAT(C.LAST_NAME,', ',C.FIRST_NAME) AS WORKER, L.CODE AS STATUS
            FROM SERVICE_DESK_WORKFLOW SDWF
            LEFT JOIN CONTACTS C ON C.RECID = SDWF.WORKER_CONTACTS_RECID
            LEFT JOIN LISTS L ON SDWF.SD_WF_STATUS_LISTS_RECID = L.RECID
            WHERE SERVICE_DESK_RECID = :sd_recid AND SDWF.RECID = :recid",
            [
                ":sd_recid" => $incident["RECID"],
                ":recid" => $callbackId[2]
            ]
        );

if(!empty($workflow)){
            $wf = $workflow[0];
            if(empty($wf["WORKER"])){
                if($wf["STATUS"] == "PENDING"){
                    if(Core_Model_Api_Servicedesk::assignWorkflow(
                        $wf["RECID"], $contact["RECID"]
                    )){
                        $assigned = "Assigned to @{$user}";
                        $icon = "checkbox.png";
                    } else {
                        $assigned = "Error: Failed to Assign Workflow...";
                    }
                } else {
                    $assigned = "Error: WF is not Pending...";
                }
            } else {
                $assigned = "WF Already Assigned to {$wf["WORKER"]}";
                $icon = "information.png";
            }
        } else {
            $assigned = "Error: Cannot find Workflow {$callbackId[1]} on {$callbackId[0]}...";
        }
    } else {
        $assigned = "Error: Cannot find Incident [{$callbackId[0]}]...";
    }
} else {
    $assigned = "Error: Cannot find User [{$payload["user"]["name"]}]...";
}

$orig = $payload["original_message"];
// the response array is the data that is returned to the original API request
$response = [
    "text" => $orig["text"],
    "attachments" => [[
        "title" => $orig["attachments"][0]["title"],
        "title_link" => $orig["attachments"][0]["title_link"],
        "text" => $orig["attachments"][0]["text"],
        "footer" => $assigned,
        "footer_icon" => $iconUrl.$icon,
        "ts" => time(),
    ]]
];