トラブルチケットオープン API 開発者ガイド

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む12読むのに数分

    • トラブルチケットオープン API を使用して、外部のチケットシステムと Now Platform の間のチケット情報を管理します。この API は、ケース [sn_customerservice_case] およびインシデント [incident] テーブルのデータを作成、更新、取得します。

    この開発者ガイドでは、トラブルチケットオープン API を拡張してさまざまなカスタマイズを行う方法について説明します。

    トラブルチケットオープン API の拡張

    トラブルチケットオープン API は、スクリプトインクルードを編集することによって拡張できます。

    これらのスクリプトインクルードは、変更の結果を理解した上でのみ編集する必要があります。
    • TMFTroubleTicketAPIConstants：定数と必要なパラメーター情報が含まれています。
    • TMFTroubleTicketAPIUtil：POST、GET、および PATCH 要求を処理する関数が含まれています。
    • TroubleTicketProcessorOOB：TMFTroubleTicketAPIUtil 内の関数をサポートするヘルパー関数が含まれています。
    • TroubleTicketProcessor：空のスクリプトインクルードファイル。このファイルを使用して、TroubleTicketProcessorOOB から上書きする関数を定義します。

    トラブルチケットオープン API を拡張して、次のカスタマイズを行います。

    必要なパラメーター

    必要な要求本文パラメーターと必要でないパラメーターを変更するには、TMFTroubleTicketAPIConstants スクリプトインクルードを更新します。デフォルトでは、チケットを作成するための要求本文 (POST) には description、severity、および ticketType のパラメーターが必要です。デフォルトでは、チケットを更新するための要求本文 (PATCH) に必要なパラメーターはありません。
    • TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA：チケットを作成するために必要な要求本文パラメーターを設定します。
    • TMFTroubleTicketAPIConstants.TROUBLE_TICKET_UPDATE_SCHEMA：チケットを更新するために必要な要求本文パラメーターを設定します。
    この例では、チケットを作成するために description、severity、status、および ticketType のパラメーターが必要です。
    // TMFTroubleTicketAPIConstants
TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA = {
    "title": "CreateTroubleTicket",
    "type": "object",
    "properties": {
        "description": {
            "type": "string"
        },
        "severity": {
            "type": "string"
        },
        "status": {
            "type": "string"
        },
        "ticketType": {
            "type": "string"
        }
    },
    "required": [
        "description",
        "severity",
        "status",
        "ticketType"
    ]
};

    要求本文の検証

    要求本文で追加の検証を実行するには、TroubleTicketProcessorOOB 関数を上書きします。TroubleTicketProcessorOOB には、デフォルトで true を返す次の 6 つのヘルパー関数が含まれています。これらの関数は、TMFTroubleTicketAPIUtil で呼び出されます。
    • verifyGetRequestForCase()：processGetRequestForCase() によって呼び出されます。
    • verifyPatchRequestForCase()：processPatchRequestForCase() によって呼び出されます。
    • verifyPostRequestForCase()：processPostRequestForCase() によって呼び出されます。
    • verifyGetRequestForIncident()：processGetRequestForIncident() によって呼び出されます。
    • verifyPatchRequestForIncident()：processPatchRequestForIncident() によって呼び出されます。
    • verifyPostRequestForIncident()：processPostRequestForIncident() によって呼び出されます。
    ヘルパー関数が false を返すと、API の操作が停止します。カスタムの検証を適用するには、TroubleTicketProcessor のものと同じ名前とパラメーターを持つ関数を作成して、TroubleTicketProcessorOOB ヘルパー関数を上書きします。新しく作成した TroubleTicketProcessor 関数は、TMFTroubleTicketAPIUtil によって呼び出され、デフォルトの TroubleTicketProcessorOOB ヘルパー関数を置き換えます。
    この例では、TroubleTicketProcessor 内の関数が TroubleTicketProcessorOOB のデフォルト関数を上書きして、name 属性の検証を実行します。
    // TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    verifyPostRequestForCase: function(caseObject, apiResponseProcessor){
        // Returning false terminates the POST request
        // Make sure to assign error message and reason
        if (caseObject.name != "Hello world") {
            apiResponseProcessor.setMessage(TMFTroubleTicketAPIConstants.MESSAGES.CASE_CREATION_FAILURE);
            apiResponseProcessor.setReason("No reason needed");
            return false;
        }
    },

    type: 'TroubleTicketProcessor'
});

    追加の REST 操作

    既存の GET、PATCH、および POST 操作以外の操作を追加するには、トラブルチケットオープン API の 追加のスクリプト化済み REST リソースを作成します 。新しいスクリプト化済み REST リソースのロジックは、既存の操作と一致する必要があります。新しい操作の関数は TMFTroubleTicketAPIUtil で定義します。

    フィールドマッピング

    レコードを作成したり更新したりする際には、API は要求本文パラメーターをケースとインシデントのレコードのフィールドにマッピングします。レコードを取得する際には、API はレコードのフィールドを応答オブジェクトの属性にマッピングします。

    TroubleTicketProcessorOOB には、PATCH または POST 要求の本文をケースやインシデントの GlideRecord にマッピングするための次の関数が含まれています。
    • mapPatchRequestToCase()
    • mapPostRequestToCase()
    • mapPatchRequestToIncident()
    • mapPostRequestToIncident()
    TroubleTicketProcessorOOB には、ケースやインシデントの GlideRecord を GET、PATCH または POST 要求の JSON 応答オブジェクトにマッピングするための次の関数が含まれています。
    • createGetResponseForCase()
    • createPatchResponseForCase()
    • createPostResponseForCase()
    • createGetResponseForIncident()
    • createPatchResponseForIncident()
    • createPostResponseForIncident()

    フィールドマッピングをカスタマイズすると、他のケースやインシデントのフィールドのデータを追加・取得したり、デフォルトのフィールドのマッピングを変更することが可能です。フィールドのマッピングをカスタマイズするには、TroubleTicketProcessor のものと同じ名前とパラメーターを持つ関数を作成して、TroubleTicketProcessorOOB マッピング関数を上書きします。新しく作成した TroubleTicketProcessor 関数は、TMFTroubleTicketAPIUtil によって使用され、デフォルトの TroubleTicketProcessorOOB マッピング関数を置き換えます。

    この例では、TroubleTicketProcessor 内の 2 つの関数で TroubleTicketProcessorOOB のデフォルトの関数を上書きして、[説明] フィールドのマッピングの変更と [契約] フィールドのマッピングの追加を行います。
    // TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    mapPostRequestToCase: function(caseGr, caseObject){
        // Override default mapping for the Description field
        caseGr.description = "All cases will be created with this description";
        // Add new mapping to the Contract field
        caseGr.contract = caseObject.contract;
     },

    createPostResponseForCase: function(caseGr, caseObject){
        // Override default mapping for the description attribute
        caseObject.description = "This will always be the retrieved description";
        // Add new contract attribute to the response object
        caseObject.contract = caseGr.contract;    
    },

    type: 'TroubleTicketProcessor'
});

    選択肢フィールドのマッピングのロジック

    [ステータス]、[優先度]、および [contact_type] フィールドは選択肢フィールドであり、各選択肢はラベルおよび対応する値で構成されます。例えば、[ステータス] フィールドが [新規]に設定されている場合、ラベルは [新規] で値は 1 です。選択肢のラベルと値の間のマッピングは、選択肢フィールドのマッピング関数を上書きすることで変更できます。

    TroubleTicketProcessorOOB には、次の選択肢フィールドのマッピング関数が含まれています。
    • transformCaseSeverity()
    • transformCaseChannel()
    • transformCaseStatus()
    • transformIncidentSeverityToUrgency()
    • transformIncidentSeverityToImpact()
    • transformIncidentChannel()
    • transformIncidentStatus()
    TroubleTicketProcessorOOB の選択肢フィールドのマッピング関数を上書きするには、TroubleTicketProcessor のものと同じ名前とパラメーターを持つ関数を作成します。新しく作成した TroubleTicketProcessor 関数は、TMFTroubleTicketAPIUtil によって使用され、デフォルトの TroubleTicketProcessorOOB 選択肢フィールドマッピング関数を置き換えます。
    この例では、TroubleTicketProcessor 内の関数が TroubleTicketProcessorOOB のデフォルトの関数を上書きして、[ステータス] フィールドの選択肢マッピングを変更します。
    // TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    transformCaseStatus: function(status){
        if (status == "Draft")
            return 1;
        else return 10;
    },

    type: 'TroubleTicketProcessor'
});