Używanie msdyn_invokeCaseProcessingAgent do wywoływania agenta zarządzania przypadkami

Użyj zdarzenia biznesowego msdyn_invokeCaseProcessingAgent, aby aktywować agenta zarządzania sprawami do wykonania następujących czynności:

  • wyodrębnij informacje z jednostki źródłowej, na przykład wiadomość e-mail, i zaktualizuj sprawę przy użyciu odpowiednich szczegółów.
  • rozwiąż konkretny przypadek.

Można użyć tego, aby rozszerzyć automatyzację spraw poza obszar domyślnych wyzwalaczy. Można na przykład wywołać Agenta Zarządzania Sprawami, gdy klient tworzy sprawę z portalu zewnętrznego, lub gdy zdarzenie CRUD występuje w tabeli niestandardowej, na przykład gdy do sprawy dodawane są nowe potwierdzenia.

Wymagania wstępne

żądanie HTTP

POST [Organization URI]/api/data/v9.2/msdyn_invokeCaseProcessingAgent

Treść wniosku

Właściwość Typ Wymagania Description
msdyn_incidentId Ciąg Yes Identyfikator przypadku (incydent), na którym powinien działać agent zarządzania przypadkami.
Przykład: "3895d023-a353-f011-877b-6045bd062e87"
msdyn_actions Tablica JSON serializowana jako ciąg Yes Definiuje, jakie działania i możliwości wykonuje Agent Zarządzania Sprawami. Szczegóły znajdziesz w poniższej sekcji.
msdyn_extraParams Obiekt JSON serializowany jako ciąg No Zapewnia dodatkowy kontekst i opcje wywołania. Zobacz Dodatkowe parametry.

Przekaż msdyn_actions i msdyn_extraParams jako kod JSON zapisany w ciągach znaków, a nie jako tablice JSON lub obiekty w ciele żądania.

obiekt tablicy msdyn_actions

Właściwość Typ Wymagania Description
action Ciąg Yes Definiuje akcję przetwarzania spraw do uruchomienia.
Wartości:
  • rozwiązanie: rozwiąż problem, korzystając z możliwości rozwiązywania problemów agenta zarządzania przypadkami.
  • wzbogacić: wyodrębnia informacje z jednostki źródłowej, na przykład wiadomość e-mail, i aktualizuje sprawę przy użyciu odpowiednich szczegółów.
    Jednostka źródłowa musi być dostępna i zawierać odpowiednie informacje o przypadku
poziomAutomatyzacji Ciąg No Dla zwykłych wywołań Agent zarządzania przypadkiem korzysta z trybu automatyzacji skonfigurowanego przez administratora, a nie wartości Full lub Semi podanej tutaj. Jeśli msdyn_extraParams.requestProcessed jest true, payload akcji jest używany w stanie dostarczonym, zamiast być aktualizowany na podstawie skonfigurowanych ustawień.
sourceContextEntity Ciąg Yes Jest to wymagana wartość dla wzbogacania sprawy i opcjonalna dla rozwiązania sprawy. Jednostka źródłowa, taka jak wiadomość e-mail lub konwersacja, która musi zostać użyta do zaktualizowania sprawy.
Przykład: "emails(0e20cf92-f663-f011-bec1-000d3a3622ba)"
customAgentOutput Obiekt JSON serializowany jako ciąg No Dla resolve dostarcza wyjście niestandardowego agenta w asynchronicznym callbacku. Obiekt korzysta z kontraktu wyjściowego niestandardowego agenta, w tym responseType, message, handlingOptions, customAgentName, oraz templateId.

Dodatkowe parametry

Obiekt msdyn_extraParams obsługuje następujące właściwości.

Właściwość Typ Wymagania Description
additionalInformation Tablica obiektów No Dostarcza informacje z zewnętrznego systemu do wykrywania intencji. Każdy obiekt zawiera key do identyfikacji informacji, value z treścią oraz keyDescription, który wyjaśnia, co treść reprezentuje. Wszystkie trzy właściwości są łańcuchami znaków.
triggerReason Ciąg No Identyfikuje, dlaczego agent jest wywoływany. Na przykład użyj customAgentCallback, gdy niestandardowy agent dzwoni ponownie do Case Management Agent.
refreshIntentFamily logiczny No Gdy true, ponownie określana jest rodzina intencji przy użyciu silnika reguł zamiast rekordu msdyn_intententity z pamięci podręcznej. Dotyczy to tylko wtedy, gdy flaga funkcji RefreshIntentFamilyInCMAFlow jest włączona.

Przykładowe żądanie

{
  "msdyn_incidentId": "5ad2ac2c-6363-f011-bec2-6045bd026457",
  "msdyn_actions": "[{\"action\":\"enrich\",\"sourceContextEntity\":\"emails(0e20cf92-f663-f011-bec1-000d3a3622ba)\"},{\"action\":\"resolve\",\"automationLevel\":\"Full\"}]"
}

Odpowiedź

  • Powodzenie: zwraca protokół HTTP 204 No Content z pustą treścią.
  • Błąd: Standardowa odpowiedź o błędzie OData.

Przykładowy kod

W poniższym przykładzie wywołujesz Case Management Agent z wtyczek Dataverse lub własnego kodu, uruchamiając żądanie msdyn_invokeCaseProcessingAgent organizacyjne. Agent aktualizuje sprawę, używając powiązanej encji e-mail, a następnie przetwarza rozwiązanie sprawy w trybie automatyzacji skonfigurowanym przez administratora.

Przykład 1

CrmServiceClient GetService()
{
    string orgUrl = "";
    string username = "";
    string connectionString = $"AuthType=OAuth;Username={username};Url={orgUrl};AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=http://localhost;LoginPrompt=Auto";
    CrmServiceClient svc = new CrmServiceClient(connectionString);
    return svc;
}

public class InvokeCaseProcessingAgentRequest
{
    [JsonProperty("msdyn_incidentId")]
    public string incidentid { get; set; }

    [JsonProperty("msdyn_actions")]
    public List<AgentAction> actions { get; set; }
}

public class AgentAction
{
    [JsonProperty("action")]
    public AgentActionType action { get; set; }

    [JsonProperty("sourceContextEntity")]
    public string sourceContextEntity { get; set; }

    [JsonProperty("automationLevel")]
    public AutomationLevel? automationLevel { get; set; }
}

[JsonConverter(typeof(StringEnumConverter))]
public enum AgentActionType
{
    [EnumMember(Value = "enrich")]
    Enrich,
    [EnumMember(Value = "resolve")]
    Resolve
}

[JsonConverter(typeof(StringEnumConverter))]
public enum AutomationLevel
{
    [EnumMember(Value = "Full")]
    Full,
    [EnumMember(Value = "Semi")]
    Semi
}

void Main()
{
    var service = GetService();
    var actions = new List<AgentAction>()
    {
        new AgentAction()
        {
            action = AgentActionType.Enrich,
            sourceContextEntity = "emails(0e20cf92-f663-f011-bec1-000d3a3622ba)"
        },
        new AgentAction()
        {
            action = AgentActionType.Resolve,
            automationLevel = AutomationLevel.Full
        },
    };
    var req = new OrganizationRequest("msdyn_invokeCaseProcessingAgent")
    {
        ["msdyn_incidentId"] = new Guid("8f2db50d-0c64-f011-bec2-000d3a3b776a"),
        ["msdyn_actions"] = JsonConvert.SerializeObject(actions)
    };
    service.Execute(req);
}

Przykład 2

function invokeCaseManagementAgent() {
  var data = JSON.stringify({
    "msdyn_incidentId": "020edf2f-7d3f-4a69-bd26-030736604eeb",
    "msdyn_actions": "[{\"action\":\"enrich\",\"sourceContextEntity\":\"emails(0e20cf92-f663-f011-bec1-000d3a3622ba)\"},{\"action\":\"resolve\",\"automationLevel\":\"Full\"}]"
  });
  var xhr = new XMLHttpRequest();
  xhr.withCredentials = true;
  xhr.addEventListener("readystatechange", function() {
    if(this.readyState === 4) {
      console.log(this.responseText);
    }
  });
  xhr.open("POST", Xrm.Utility.getGlobalContext().getClientUrl()+"/api/data/v9.2/msdyn_invokeCaseProcessingAgent");
  xhr.setRequestHeader("Cache-Control", "no-cache");
  xhr.setRequestHeader("Accept", "*/*");
  xhr.setRequestHeader("Content-Type", "application/json");
  xhr.send(data);
}

invokeCaseManagementAgent();

Dostarczaj dodatkowe informacje z zewnętrznego systemu

Użyj additionalInformation, aby podać kontekst, taki jak zawartość załącznika czy status gwarancji, do wykrywania intencji. To żądanie Web API wysyła oba parametry w postaci zserializowanego ciągu JSON.

{ 

  "msdyn_incidentId": "00000000-0000-0000-0000-000000000000", 
  "msdyn_actions": [ 
    { "action": "resolve", "sourceContextEntity": "emails(<email-guid>)" } 
  ], 
  "msdyn_extraParams": { 
    "triggerReason": "customAgentCallback", 
    "additionalInformation": [ 
      { "key": "attachmentContent", "value": "This is my attachment content", 
        "keyDescription": "File attachment content in natural language" }, 
      { "key": "warrantyStatus", "value": "Fulfilled", 
       "keyDescription": "Current warranty fulfillment status" } 
    ] 
  } 
}

Zwróć asynchroniczny wynik agenta niestandardowego

Gdy niestandardowy agent zwraca Wait, Agent Zarządzania Sprawami staje się bezczynny, podczas gdy niestandardowy agent wykonuje pracę asynchroniczną. Aby kontynuować przetwarzanie, wywołaj resolve z akcją customAgentOutput i wartością responseType, której Wait nie jest msdyn_invokeCaseProcessingAgent. Informacje o przebiegu integracji znajdziesz w artykule Jak działa integracja.

Następujące żądanie Web API wysyła customAgentOutput jako ciąg JSON wewnątrz tablicy msdyn_actions przekształconej do postaci ciągu. Zamień identyfikator przypadku, nazwę schematu agenta i identyfikator szablonu na wartości ze swojego środowiska.

{ 

  "msdyn_incidentId": "<case-guid>", 
  "msdyn_actions": [ { 
    "action": "resolve", 
    "customAgentOutput": { "responseType": "Resolved", "message": "<message>", 
      "handlingOptions": { "needsReview": "true" }, 
      "customAgentName": "<agent schema name>", "templateId": "<template-guid>" } 
  } ] 
}
  • Ostatnia aktualizacja o