XML Descriptions for Integration Template

 <Scenario Id="AuthMethod" Type="AUTH">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="AuthMethod" Value="oauth2"></Parameter>
    <Parameter Name="AuthEndPoint" Value="https://api.example.com/oauth/v2/auth?client_id={{.client_id}}"></Parameter>
    <Parameter Name="TokenEndPoint" Value="https://api.example.com/oauth/v2/token?client_id={{.client_id}}&amp;client_secret={{.client_secret}}"></Parameter>
    <Parameter Name="AdditionalQueryString"></Parameter>
    <Parameter Name="Scope" Value="contacts.read,contacts.write,calls.read,calls.write,user.read,user.write"></Parameter>
    <Parameter Name="CredentialType"></Parameter>
    <Parameter Name="Base64EncodedCredential"></Parameter>
    <Parameter Father="CustomFieldList" Name="client_id" Editor="password" Title="Client ID"></Parameter>
    <Parameter Father="CustomFieldList" Name="client_secret" Editor="password" Title="Client Secret"></Parameter>
   </Parameters>
   <Requests></Requests>
  </Scenario>

Scenario element

The <Scenario> element has the following attributes:

Attribute	Description
Id	The unique identifier of the scenario, the value should be fixed as AuthMethod.
Type	The type of the scenario, the value is AUTH, which means the scenario will execute authentication operations.

Parameter element

Attribute	Description
Name	The name of the authentication parameter.
Value	The value of the authentication parameter.
Father	The name of a parent parameter (should be fixed as CustomFieldList), which serves as a container for the following child parameters, organizing custom fields that allow users to input values for the associated parameters in the configuration UI. Note: The variables captured in the custom fields are accessible for all the subsequent requests in the template. Name: The variable name of the custom field, which can be reference in the template. Editor: The type of the custom field. Valid value: string: A standard input field where users can enter plain text. password: A specialized input field for sensitive information, with text masked for privacy. list: A selectable list that allows users to choose from a pre-defined list of options. Title: The title of the custom field. Value: The pre-defined list of options.

Authentication parameters

Parameter	Description
AuthMethod	Authentication method. Valid value: none: This method is used when there is no authentication required, or when the CRM/Helpdesk only requires relevant variables for data exchange, such as an API Key or a webhook URL. basic: This method authenticate requests using credentials, such as username and password or an API key. These credentials are be base64-encoded into a basic string and included in a header field of every HTTP request sent to the CRM/Helpdesk. oauth2: This method uses tokens to grant access without sharing credentials. It requires obtaining the necessary header and other parameters (e.g. OAuth access token) using specific API requests to the CRM/Helpdesk.
AuthEndPoint	The CRM/Helpdesk authorization URL that needs to be opened to initiate the authorization process. Note: This parameter is only available for oauth2 authentication method.
TokenEndPoint	The CRM/Helpdesk API request URL for getting access token and refresh token. Note: This parameter is only available for oauth2 authentication method.
AdditionalQueryString	If the CRM/Helpdesk system authenticates requests using query parameters instead of scope, you can add the query variables in this parameter. Note: This parameter is only available for oauth2 authentication method.
Scope	Specify the scope of CRM/Helpdesk data that the PBX is allowed to access. Note: This parameter is only available for oauth2 authentication method.
CredentialType	The type of the credential. Note: This parameter is only available for basic authentication method. Valid value: username_password api_key
Base64EncodedCredential	Define the combination format of the credential variables, which will be used to generate the basic authentication string. Note: This parameter is only available for basic authentication method. E.g. {{.username:.password}} or {{.api_key:}}.

<Scenario Id="UserAssociation" Type="REST">
   <Parameters></Parameters>
   <Requests>
    <Request Name="UserAssociation" Method="GET" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/v1/users?type=ActiveUsers">
     <Parameters></Parameters>
     <Outputs>
      <Output Name="UserUniqueId" Path="users.#.id" Type=""></Output>
      <Output Name="FirstName" Path="users.#.First_Name" Type=""></Output>
      <Output Name="LastName" Path="users.#.Last_Name" Type=""></Output>
      <Output Name="Email" Path="users.#.Email" Type=""></Output>
     </Outputs>
    </Request>
   </Requests>
</Scenario>

Scenario element

The <Scenario> element has the following attributes:

Attribute	Description
Id	The unique identifier of the scenario, the value should be fixed as UserAssociation.
Type	The type of the scenario, the value is REST, which means the scenario will execute a REST API using an HTTP request.

Request element

The <Request> element has the following attributes:

Attribute	Description
Name	The name of the request, which helps to identify the request within the scenario. The value should be fixed as UserAssociation.
Method	The HTTP method to be used for the request. In this scenario, the default HTTP method is GET, you can modify it if necessary.
ResponseType	The expected response format for the request, which should be in JSON format (application/json).
RequestEncoding	How the request should be encoded. In this scenario, the value is empty.
URLFormat	The request URL of the API endpoint.

Output element

The <Output> element has the following attributes:

Attribute	Description
Name	The name of the output variable, which represents the variables need to be retrieved from the response data.
Path	The location of the desired data field within the API response, using a path syntax to access nested data (e.g. users.#.id).
Type	The data type of the output variable. In this template, the type is fixed as string.

Variables

Variable	Description
UserUniqueId	The unique ID of the CRM/Helpdesk user.
FirstName	The first name of the user.
LastName	The last name of the user.
Email	The email of the user.

  <Scenario Id="SyncContactAuto" Type="REST">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="ContactUrlType" Value="retrieve_from_contact"></Parameter>
    <Parameter Name="URLFormat"></Parameter>
    <Parameter Name="ContactFieldForUri" Value="data.#.contactUrl"></Parameter>
    <Parameter Name="ContactsIdEnable" Value="1"></Parameter>
    <Parameter Name="FirstNameEnable" Value="1"></Parameter>
    <Parameter Name="BusinessNumberEnable" Value="1"></Parameter>
    <Parameter Name="CustomValueEnable" Value="0"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="Contacts" Method="GET" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/v1/Contacts/search?criteria=((Phone:equals:{{.Phone}})or(Home_Phone:equals:{{.Phone}})or(Mobile:equals:{{.Phone}})or(Asst_Phone:equals:{{.Phone}}))">
     <Parameters></Parameters>
     <Outputs>
      <Output Name="ContactsId" Path="data.#.id" Type=""></Output>
      <Output Name="FirstName" Path="data.#.First_Name" Type=""></Output>
      <Output Name="BusinessNumber" Path="data.#.Phone" Type=""></Output>
      ...
      <Output Name="CustomValue" Path="data.#.Owner" Type=""></Output>
     </Outputs>
    </Request>
   </Requests>
  </Scenario>

Scenario element

The <Scenario> element has the following attributes:

Attribute	Description
Id	The unique identifier of the scenario, the value should be fixed as SyncContactAuto.
Type	The type of the scenario, the value is REST, which means the scenario will execute a REST API using an HTTP request.

Parameter element

The <Parameter> element provides has the following attributes:

Attribute	Description
Name	The name of the configuration settings used in the scenario.
Value	The value of the configuration settings.

Configuration settings

Setting	Description
ContactUrlType	Specify the method for retrieving the contact URL for call popup. Valid value: specify_url_format: Configure the call popup URL by specifying the URL format, where you can use variables to dynamically construct the URL. retrieve_from_contact: Extract the contact URL directly from a specific field in the contact search response, where the contact URL can be retrieved.
URLFormat	The expression of the Contact URL. The following variables can be used to construct the URL. The variables captured from the custom field inputs in the authentication process. ContactSyncType: The contact type, which is retrieve from the name of the request used to search specific types of contact. ContactId: The contact ID, which is retrieved from the response data in this scenario. CustomValue: A custom field, which is retrieved from the response data in this scenario. For example, {{.crm_url}}/crm/{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}. Note: If the provided variables do not meet your requirements, you can define additional requests and retrieve the corresponding values for your desired variables. For more information, see Extended Configurations - Retrieve Additional Variables.
ContactFieldForUri	The JSON path used to retrieve the corresponding field for the contact URL from the response data. For example, .data.#.contactUrl.
ContactsIdEnable	Whether to retrieve contact's ID from the response data. The value should be set to 1.
FirstNameEnable	Whether to retrieve the contact's first name from the response data. The value should be set to 1.
LastNameEnable	Whether to retrieve the contact's last name from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
CompanyEnable	Whether to retrieve the contact's company from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
EmailEnable	Whether to retrieve the contact's email from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
BusinessNumberEnable	Whether to retrieve the contact's business phone number from the response data. Note: At least one phone number is required. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
BusinessNumber2Enable	Whether to retrieve the contact's second business phone number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
BusinessFaxNumberEnable	Whether to retrieve the contact's business fax number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
MobileNumberEnable	Whether to retrieve the contact's mobile number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
MobileNumber2Enable	Whether to retrieve the contact's second mobile number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
HomeNumberEnable	Whether to retrieve the contact's home number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
HomeNumber2Enable	Whether to retrieve the contact's second home number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
HomeFaxNumberEnable	Whether to retrieve the contact's home fax number from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
OtherNumberEnable	Whether to retrieve the contact's other type of number (other than business number or home number) from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
ZipCodeEnable	Whether to retrieve the zip code from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
StreetEnable	Whether to retrieve the street from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
CityEnable	Whether to retrieve the city from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
StateEnable	Whether to retrieve the state/province from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
CountryEnable	Whether to retrieve the country from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
RemarkEnable	Whether to retrieve the remark for the contact from the response data. Valid value: 0: Do not retrieve the data. 1: Retrieve the data.
CustomValueEnable	Whether to enable a custom variable, which can be used to construct the Contact's URL. Valid value: 0: Disable. 1: Enable.

Request element

The <Request> element has the following attributes:

Attribute	Description
Name	The name of the request, which helps to identify the request within the scenario. Note: The value should be the actual name of the specific contact type to be searched in the CRM/Helpdesk system, and will be referenced as a ContactSyncType variable.
Method	The HTTP method to be used for the request. In this scenario, the default HTTP method is GET, you can modify it if necessary.
ResponseType	The expected response format for the request, which should be in JSON format (application/json).
RequestEncoding	How the request should be encoded. In this scenario, the value is empty.
URLFormat	The request URL of the API endpoint.

Output element

The <Output> element has the following attributes:

Attribute	Description
Name	The name of the output variable, which represents the variables need to be retrieved from the response data.
Path	The location of the desired data field within the API response, using a path syntax to access nested data (e.g. users.#.id).
Type	The data type of the output variable. In this template, the type is fixed as string.

Variables

Variable	Description
ContactsId	(Required) The unique ID of the contact.
FirstName	(Required) The first name of the contact.
LastName	The last name of the contact.
Company	The company of the contact.
Email	The email of the contact.
BusinessNumber	The business phone number of the contact. Note: At least one phone number is required.
BusinessNumber2	The second business phone number of the contact.
BusinessFaxNumber	The business fax number of the contact.
MobileNumber	The mobile number of the contact.
MobileNumber2	The second mobile number of the contact.
HomeNumber	The home number of the contact.
HomeNumber2	The second home number of the contact.
HomeFaxNumber	The home fax number of the contact.
OtherNumber	The other type of phone number of the contact.
ZipCode	Zip code.
Street	Street.
City	City.
State	State or province.
Country	Country.
Remark	Remark.
CustomValue	A custom variable, which is used to construct the Contact's URL.

 <Scenario Id="CreateNewContact" Type="REST">
   
   <Parameters></Parameters>
   <Requests>
    <Request Name="Contacts" Method="POST" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/v1/Contacts">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"data": [{"Last_Name":"{{.LastName}}","First_Name":"{{.FirstName}}","Phone":"{{.BusinessNumber}}";}]}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
  </Scenario>

Scenario element

The <Scenario> element has the following attributes:

Attribute	Description
Id	The unique identifier of the scenario, the value should be fixed as CreateNewContact.
Type	The type of the scenario, the value is REST, which means the scenario will execute a REST API using an HTTP request.

Request element

The <Request> element has the following attributes:

Attribute	Description
Name	The name of the request, which helps to identify the request within the scenario. Note: The value should be the actual name of the specific contact type to be created in the CRM/Helpdesk system.
Method	The HTTP method to be used for the request. In this scenario, the HTTP method is POST.
ResponseType	The expected response format for the request, which should be in JSON format (application/json).
RequestEncoding	How the request should be encoded. In this scenario, the value is empty.
URLFormat	The request URL of the API endpoint.

Parameter element

The <Parameter> element nested within the <Request> element defines the parameters included in the request body.

Attribute	Description
Name	The name of the parameter, which should be fixed as Data.
Type	The type of the parameter, which should be fixed as Body.
Value	Defines the required parameters to be passed through the request body, within a data structure. The parameter values can be retrieved from the pre-defined variables in the PBX system. Note: The format should follows XML parameter standards. For example, if a line break is required, you must use the escape character 
 to represent a newline.

Variables

Note: Only required variables are listed here. If you need additional parameters and variables, see Extended Configurations - Retrieve Additional Variables.

Variable	Description
{{.LastName}}	The last name of the contact.
{{.FirstName}}	The first name of the contact.
{{.BusinessNumber}}	The phone number of the contact.

<Scenario Id="CreateNewTicket" Type="REST" >
   <Presets></Presets>
   <Parameters>
    <Parameter Name="EnableSubject" Value="1"></Parameter>
    <Parameter Name="Subject" Value="{{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}"></Parameter>
    <Parameter Name="EnableDescription" Value="1"></Parameter>
    <Parameter Name="Description" Value="{{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="CreateNewTicket" Method="POST" Weight="0" ResponseType="application/json" RequestEncoding="" URLFormat="https://{{.domain}}/api/v1/tickets">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"subject":"{{.Subject}}","contactId":"{{.ContactId}}","phone":"{{.ContactNumber}}","description":"{{.Description}}";}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
</Scenario>

Scenario element

The <Scenario> element has the following attributes:

Attribute	Description
Id	The unique identifier of the scenario, the value should be fixed as CreateNewTicket.
Type	The type of the scenario, the value is REST, which means the scenario will execute a REST API using an HTTP request.

Parameter element

Attribute	Description
Name	The name of the configuration settings used in the scenario.
Value	The value of the configuration settings.

Configuration settings

Settings	Description
EnableSubject	Whether to allow users to customize the subject of the ticket. Valid value: 0: Disable. 1: Enable.
Subject	Specify the default value of the subject. Note: The default value is {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}. For more supported variables, see the parameter variable list.
EnableDescription	Whether to allow users to customize the description of the ticket. Valid value: 0: Disable. 1: Enable.
Description	Specify the default value of the description. Note: The default value is {{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}. For more supported variables, see the parameter variable list.

Request element

The <Request> element has the following attributes:

Attribute	Description
Name	The name of the request, which helps to identify the request within the scenario. The value should be fixed as CreateNewTicket.
Method	The HTTP method to be used for the request. In this scenario, the HTTP method is POST.
ResponseType	The expected response format for the request, which should be in JSON format (application/json).
RequestEncoding	How the request should be encoded. In this scenario, the value is empty.
URLFormat	The request URL of the API endpoint.

Parameter element

The <Parameter> element nested within the <Request> element defines the parameters included in the request body.

Attribute	Description
Name	The name of the parameter, which should be fixed as Data.
Type	The type of the parameter, which should be fixed as Body.
Value	Defines the required parameters to be passed through the request body. The parameter values can be retrieved from the pre-defined variables in the PBX system. Note: The format should follows XML parameter standards. For example, if a line break is required, you must use the escape character 
 to represent a newline.

Variables

Note: Only required variables are listed here. If you need additional parameters and variables, see Extended Configurations - Retrieve Additional Variables.

Variable	Description
Variables obtained from the AuthMethod scenario	The variables captured from the user input for authentication process.
{{.Subject}}	The subject of the ticket. This variable value is retrieved from the Subject parameter.
{{.Description}}	The description of the ticket. The variable value is retrieved from the Description parameter.
{{.Time}}	The time the call was made or received (in PBX system's time format).
{{.StartTimeUnix }}	The Unix timestamp of the call start time.
{{.EndTimeUnix}}	The Unix timestamp of the call end time.
{{.Call_From}}	The name and number of the calling party that initiated the call. Format: Caller’s name <Caller’s number>.
{{.CallerName}}	Caller’s name.
{{.CallerNumber}}	Caller’s number.
{{.CalleeName}}	Callee’s name.
{{.CalleeNumber}}	Callee’s number.
{{.CrmId}}	The unique ID of the CRM/Helpdesk user associated with a PBX extension.
{{.ExtensionFirstName}}	The first name of the extension user.
{{.ExtensionLastName}}	The last name of the extension user.
{{.ExtensionEmail}}	The email of the extension user.
{{.ContactSyncType}}	The type of the contact.
{{.ContactNumber}}	The number of the contact.
{{.ContactId}}	The unique ID of a contact.
{{.TicketId}}	The unique ID of the ticket created based on a call. Note: To get the ticket ID, you need to configure additional settings in the template. For more information, see Extended Configuration - Retrieve Ticket ID.
{{.CallDuration}}	The time between the call stared and the call ended.
{{.Talk_Duration}}	The time between the call answered and the call ended (in a format of hh:mm:ss).
{{.Talk_Duration_Sec}}	The time between the call answered and the call ended (in seconds).
{{.Communication_Type}}	The direction of the call. Possible value: Inbound: Inbound call. Outbound: Outbound call.
{{.Call_Status}}	The processing status of the call. Possible value: Missed: A call that was not answered. Completed: A call that was successfully connected and completed.
{{.Call_Log_Status}}	The status of the call. Possible value: Missed Call: A call that was not answered, Outgoing Call: An outbound call that was initiated by the system. Incoming Call: An inbound call that was received by the system. Voicemail: A call that was not answered and was directed to voicemail.
{{.CallDisposition}}	The disposition of the call. Possible value: MISSED: The call was not answered. VOICEMAIL: The call was sent to voicemail. BUSY: The recipient was on another call and could not answer. ANSWERED: The call was successfully answered. NO ANSWER: The recipient did not answer the call.

  <Scenario Id="CallJournal" Type="REST">
   <Presets></Presets>
   <Parameters>
    <Parameter Name="EnableSubject" Value="1"></Parameter>
    <Parameter Name="Subject" Value="Extension Call"></Parameter>
    <Parameter Name="EnableDescription" Value="1"></Parameter>
    <Parameter Name="Description" Value="Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}"></Parameter>
    <Parameter Name="EnablePlayCallRecording" Value="1"></Parameter>
    <Parameter Name="PlayCallRecording" Value="0"></Parameter>
   </Parameters>
   <Requests>
    <Request Name="CallJournal" Method="POST" Weight="0" ResponseType="application/json" RequestEncoding="" URLFormat="https://www.api.example.com/crm/v2/Calls">
     <Parameters>
      <Parameter Name="Data" Type="Body" Value="{"data"[{"{{.Owner}}{{.WhoModule}}": {"Description":"{{.Description}}","Voice_Recording__s":"{{.RecordPath}}","Call_Start_Time":"{{TimeFormat .StartTimeUnix "yyyy-MM-ddTHH:mm:ss-z" "1"}}","Subject&":"{{.Subject}}","Call_Type": "Inbound","Call_Result": "{{.Call_Log_Status}}","Call_Duration": "{{.Talk_Duration_Sec}}"}}]}"></Parameter>
     </Parameters>
     <Outputs></Outputs>
    </Request>
   </Requests>
  </Scenario>

Set custom request headers

If custom request headers are needed, you can add parameter(s) with the type set to Header. This will add the headers to the request body.

As shown in the following example, a X-Auth-Token header is used to pass the API key. The Father attribute (fixed as PopulateTemplateString) groups a set of related parameters, while the Type (fixed as Header) indicates that the parameter is intended to be passed as an HTTP header. The Name and value specify the header's name and value. In this case, the header included in the request would be X-Auth-Token:{{.api_key}}.

 <Requests>
        <Request Name="contacts" Method="GET" ResponseType="application/json" URLFormat="https://api.example.come/contacts/search?number={{.Phone}}">
          <Parameters>
            <Parameter Father="PopulateTemplateString" Name="X-Auth-Token" Type="Header" Value="{{.api_key}}" />  
          </Parameters>
          <Outputs>
           ...
          </Outputs>
        </Request>

Identify token errors

In the AuthMethod scenario, you can add a parameter TokenInvalid to help identify whether the issue in the request is related to the token or other underlying problems.

You can refer to the following example, and change the Value to the token-related error code or specific content. If the HTTP status code returned is not 200 and the response body contains the content specified in Value, the error will recognized as TokenInvalid.

   <Scenario Id="AuthMethod" Type="AUTH">
      <Presets />
      <Parameters>
        <Parameter Name="AuthMethod" Value="oauth2" />
        ...
        <Parameter Father="TokenErrorMap" Type="TokenInvalid" Name="TokenInvalid" Value="INVALID_TOKEN" />
        ...
      </Parameters>
      <Requests />
      <Responses />
    </Scenario>

Retrieve additional variables for global use

If you require additional variables beyond the provided ones, if you want to use certain common information globally during the integration process, you can define a GetGlobalInfo scenario and set up the related requests to retrieve the necessary values.

When the integration is completed or the PBX is started, requests set within the GetGlobalInfo scenario will be sent to the CRM/Helpdesk system, and the required variables will be stored in the Output elements, with their names directly corresponding to the variable names, making them accessible for reference in other scenarios (excluding the authentication scenario).

As shown in the following example, the GetGlobalInfo scenario contains requests for retrieving essential information DepartmentId and PortalName.

<Scenario Id="GetGlobalInfo" Type="REST">
      <Presets />
      <Parameters />
      <Requests>
        <Request Name="GetDepartments" Method="GET" ResponseType="application/json" URLFormat="https://desk.example.{{.domain_suffix}}/api/v1/departments">
          <Parameters />
          <Outputs>
            <Output Name="DepartmentId" Path="data.#.id" />
          </Outputs>
        </Request>
        <Request Name="GetOrganizations" Method="GET" ResponseType="application/json" URLFormat="https://desk.example.{{.domain_suffix}}/api/v1/organizations">
          <Parameters />
          <Outputs>
            <Output Name="PortalName" Path="data.#(portalName!="").portalName" />
          </Outputs>
        </Request>
      </Requests>
</Scenario>

Supplement contact query information

If the initial query for contact information does not return all the necessary information you need, further queries may be required using the returned contact ID or other contact information.

As shown in the example below, in a scenario of contact synchronizing, the initial query request does not return the desired phone numbers.

<Scenario Id="SyncContactAuto" Type="REST">
   <Presets />
   <Parameters>
     <Parameter Name="ContactUrlType" Value="specify_url_format" />
        ...
     </Parameters>
     <Requests>
       <Request Name="contacts" Method="GET" ResponseType="application/json" URLFormat="https://{{.subdomain}}.example.com/api/v2/users?query=phone:{{UrlEncode .Phone}}&role[]=end-user">
         <Parameters />
         <Outputs Next="GetIdentities">
            <Output Name="ContactsId" Path="users.#.id" />
            <Output Name="FirstName" Path="users.#.name" />
            <Output Name="BusinessNumber" Path="users.#.phone" />
            ...   
            //The following phone number fields returns empty.                        
            <Output Name="BusinessNumber2" Path=""></Output>       
            <Output Name="BusinessFaxNumber" Path=""></Output>
            <Output Name="MobileNumber" Path=""></Output>
            <Output Name="MobileNumber2" Path=""></Output>
            <Output Name="HomeNumber" Path=""></Output>
            <Output Name="HomeNumber2" Path=""></Output>
            ...
          </Outputs>
        </Request>
      </Requests>
    </Scenario>

In this case, you can perform a further query to retrieve the desired numbers by chaining scenarios, as described in the following steps:

1. Add a Next Attribute in the original scenario

   In the contact synchronizing scenario, add a Next attribute in the <Outputs> element of the initial query request. The attribute value must be the name of the desired request configured in the Common scenario. In this example, the request name is GetIdentities.

   <Outputs Next="GetIdentities">

2. Create a Common scenario

   Create a scenario named Common with a type of REST (both the name and type are fixed), then add a request named GetIdentities to query additional contact information using the variable {{.ContactsId}} obtained from the initial request.

   <Scenario Id="Common" Type="REST">
     <Presets></Presets>
     <Parameters></Parameters>
     <Requests>
       <Request Name="GetIdentities" Method="GET" URLFormat="https://{{.subdomain}}.example.com/api/v2/users/{{.ContactsId}}/identities"  ResponseType="application/json">
         <Parameters></Parameters>
         <Outputs>
           <Output Name="BusinessNumber2" Path="identities.#(type=="phone_number")#|1.value"></Output>
           <Output Name="BusinessFaxNumber" Path="identities.#(type=="phone_number")#|2.value"></Output>
           <Output Name="MobileNumber" Path="identities.#(type=="phone_number")#|3.value"></Output>
           <Output Name="MobileNumber2" Path="identities.#(type=="phone_number")#|4.value"></Output>
           <Output Name="HomeNumber" Path="identities.#(type=="phone_number")#|5.value"></Output>
           <Output Name="HomeNumber2" Path="identities.#(type=="phone_number")#|6.value"></Output>
           <Output Name="HomeFaxNumber" Path="identities.#(type=="phone_number")#|7.value"></Output>
           <Output Name="OtherNumber" Path="identities.#(type=="phone_number")#|8.value"></Output>
          </Outputs>
       </Request>
      </Requests>
   </Scenario>

   Since the request is referenced via the NEXT attribute in the original scenario, the variable from the initial query will be passed to the request. The request will execute and backfill the Outputs into the initial request's response to complete the information.

Retrieve TicketID for further operations

In a Helpdesk integration template, you can configure additional settings to retrieve the ticket ID for subsequent operations, such as updating the ticket or referencing the variable in call journal.

For example, when the ticket is created before the call (i.e. when the phone rings), it might be missing some information. In this case, you can update the information for the created ticket by using the TicketId in the corresponding call record later, as described in the following steps:

<Scenario Id="CreateNewTicket" Type="REST">
   <Presets />
   <Parameters>
      <Parameter Name="EnableSubject" Value="1" />
      ...
      <Parameter Name="NeedSyncContact" Value="1" />
    </Parameters>
    <Requests>
       <Request Name="CreateNewTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets">
         <Parameters>
          <Parameter Name="Data" Type="Body" Value="{"departmentId":"{{.DepartmentId}}","subject":"{{.Subject}}","contactId":"{{.ContactId}}","phone":"{{.ContactNumber}}","description":"{{.Description}}"}" />
         </Parameters>
         <Outputs>
           <Output Name="TicketId" Path="id" />
         </Outputs>
        </Request>
        <Request Name="UpdateTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets/{{.TicketId}}/comments">
          <Parameters>
            <Parameter Name="Data" Type="Body" Value="{"isPublic":"true","content":"{{.Description}}"}" />
          </Parameters>
        <Outputs />
       </Request>
    </Requests>
</Scenario>

1. Retrieve ticket ID
   In the CreateNewTicket scenario, add an <Output> element to extract the ticket ID from the response of CreateNewTicket request.

   <Outputs>
     <Output Name="TicketId" Path="id" />
   </Outputs>

   This allows the system to store the TicketId for future use.
2. Update the ticket
   Add a request to update the ticket in the corresponding call record using the previously retrieved ticket ID.

   <Request Name="UpdateTicket" Method="POST" ResponseType="application/json" URLFormat="https://{{.domain}}/api/v1/tickets/{{.TicketId}}/comments">
      <Parameters>
        <Parameter Name="Data" Type="Body" Value="{"isPublic":"true","content":"{{.Description}}"}" />
      </Parameters>
      <Outputs />
   </Request>

   The ticket is updated with all necessary data after the initial creation.