XML Descriptions for Integration Template

Yeastar P-Series Cloud Edition allows you to create CRM/Helpdesk integration templates, where you can define the necessary settings, including specific API endpoints, data fields, and functional scenarios required for the integration. This topic provides detailed description of the setting elements in the XML templates.

Template conventions

The template follows the XML 1.1 standard specification. This section describes the syntax and conventions of the template.

Variable
The template supports the use of variables for dynamic data. When the template is executed, the variables referenced within the template will be replaced with their respective values.
The following table shows the source of variable values and how to reference the variables in the template.
Item Description
Source Variables in this template can be obtained form the following sources:
  • Pre-defined variables in the PBX system
  • Parameter values input by users during the integration
  • Values retrieve from the request response
    You can retrieve values from the response body by specifying a JSON path, as shown in the examples below.
    Tip: For more information about the path syntax, see GJSON Path Syntax.

    • To retrieve a response value, use the following syntax:

      <Output Name="UserUniqueId" Path="data.#.id"></Output>

    • For retrieve a value that meets specific conditions, use following syntax:

      <Output Name="BusinessNumber2" Path="identities.#(type=="phone_number")#|1.value"></Output>
Reference format Variables in this template follow the text/template syntax specification of Go Language, as shown below:
  • Standard variable: {{.varname}}
  • Conditional variable: {{ if .varname }} Welcome, member! {{ else }} Please sign up. {{ end }}
  • Function calls with variable: {{ Capitalize .varname }}
Function
The template supports the following function, which can be used in conjunction with variables to dynamically manipulating or formatting the variable value.
Function Description
TimeFormat The function can be used to customize the format of a timestamp.

Format: {{ TimeFormat Timestamp_variable "format_string" "Whether_to_convert_to_UTC_time" }}

Example: {{ TimeFormat .StartTimeUnix "yyyy-MM-ddTHH:mm:ss.000Zz" "1" }}

Assuming the value of {{.StartTimeUnix}} is 1672531199, the final output would be 2023-01-01T00:59:59.000Z.
ToMillis The function can be used to convert a seconds timestamp to a milliseconds timestamp.

Format: {{ ToMillis Timestamp_variable}}

Example: {{ ToMillis .StartTimeUnix }}

Assuming the value of {{.StartTimeUnix}} is 1672531199, the final output would be 1672531199000.
Capitalize The function can be used to capitalizes the first letter of a string.

Format: {{ Capitalize variable_string}}

Example: {{ Capitalize .variable_string }}

Assuming the value of {{.variable_string}} is hello world, the final output would be Hello world.
UrlEncode The function can be used to URL encode a string.

Format: {{ UrlEncode .variable }}

Example: {{ UrlEncode .variable}}

Assuming the value of {{.variable_string}} is hello world!, the final output would be hello%20world%21.
Elements
The templates offers the following main elements that help define the integration interactions, ensuring that the template can seamlessly connect with the third-party system and process data based on integration requirements.

The following example shows the main structure of the template.

<Information>
  <Scenarios>
    <Scenario Id="1" Type="REST">
      <Parameters>
        <Parameter Name="example" Value="example"></Parameter>
        ...
      </Parameters>
      <Requests>
        <Request Name="ExampleRequest" Method="GET" URL="https://api.example.com/getuser">
           <Outputs>
            <Output Name="ContactId" Path="data.#.id" Type="string"></Output>
            ...
          </Outputs>
        </Request>
      </Requests>
    </Scenario>
  </Scenarios>
</Information>
Main Element Description
Information

The <Information> element is a root element of the XML template, providing the basic information and configuration overview through its attributes. It also contains the <Scenarios> child element to describe the functional scenarios and integration capabilities of the template.

For the details of the attributes, see Template property.
Scenarios

The <Scenarios> element provides a collection of <Scenario> child elements, which contains further child elements, such as <Parameters>, <Requests>, and <Outputs>, to describe specific functional scenarios for the integration. The PBX will load the configured scenarios and execute the HTTP requests or operations defined within it.

The template supports the following scenarios.

Note: If the specified scenarios do not meet your requirements, you can manually edit the template configurations for supplementary usage. For more information, see Extended configurations.
Parameters The <Parameters> element is used to define a collection of parameters that are associated with the scenarios or requests.

These parameters typically include dynamic values or configuration settings required for the execution of the scenario. They can be passed in the request URL, body, or headers, depending on the use case.
Requests This <Requests> element provides a collection of requests for the scenarios to implement specific features.
Outputs The <Outputs> element contains a list of <Output> elements that define the data to be extracted from the API response.

Template property

The <Information> element provides the properties of the template, including the basic template information and configuration overview, as listed below:

Attribute Description
Provider The type of the template, with a fixed value of crm or helpdesk.
Name The name of the template.
Key Unique identifier for the template.
Logo The filename of the logo.
Remark A description or remark about the template.
Version The version of the template. E.g. 1.0.0.
AuthType The authentication method used in the integration.
  • none: None authentication.
  • basic: Basic authentication.
  • oauth2: OAuth2 authentication.
  • bearertoken: Bearer Token authentication.
MaxConcurrentRequest The maximum number of concurrent HTTP requests allowed to the CRM/Helpdesk.
UserAssociation Whether the User Association feature is enabled or not.
  • 0: Disabled.
  • 1: Enabled.
CallJournal Whether the Call Journal feature is enabled or not.
  • 0: Disabled.
  • 1: Enabled.
CreateNewContact Whether the Create New Contact feature is enabled or not.
  • 0: Disabled.
  • 1: Enabled.
CreateNewTicket Whether the Create New Ticket Automatically feature is enabled or not.
  • 0: Disabled.
  • 1: Enabled.

Authentication scenario

This scenario defines the authentication method used by the CRM/Helpdesk system. The structure of the scenario and its key elements are outlined as below:

 <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="ContentType" Value="application/json"></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 Name="TokenRefreshInterval" Value="25"></Parameter>
    <Parameter Name="TokenRefreshBody" Value="grant_type=refresh_token&amp;refresh_token={{.refresh_token}}"></Parameter>
    <Parameter Name="TokenRefreshEndpointMethod" Value="post"></Parameter>
    <Parameter Name="TokenRefreshEndpoint" Value="https://api.example.com/oauth2/token"></Parameter>
    <Parameter Name="TokenRefreshContentType" Value="application/x-www-form-urlencoded"></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>
    <Parameter Father="PopulateTemplateString" Name="Content-Type" Type="Header" Value="application/json" Description="The format of the request body"/>
    <Parameter Father="PopulateTemplateString" Name="Accept" Type="Header" Value="application/json" Description="The expected response data format from the server "/>
    <Parameter Father="PopulateTemplateString" Name="X-CSRF-Token" Type="Header" Value="f3e1a2b4c5d6e7f8g9h0" Description="Prevent Cross-Site Request Forgery (CSRF) attacks"/>
    <Parameter Father="PopulateTemplateString" Name="X-Client-Id" Type="Header" Value="{{.client_id}}" Description="for client identification"/>
    <Parameter Father="FollowUpList" Name="ffb425cb-565d-49cd-92be-3290d0ab5129" Type="FollowUpRequest" Value="" IsDelete="0">
         <Parameter Name="TriggeredEvent" Value="token_retrieved"></Parameter>
         <Parameter Name="RequestMethod" Value="post"></Parameter>
         <Parameter Name="Url" Value="https://api.example.com/v1/install/verify"></Parameter>
         <Parameter Name="Headers" Value="{"Content-Type":"application/json","X-Request-ID": "550e8400-e29b-41d4-a716-446655440000","User-Agent":"YourApp-Integration/1.0.0"}"></Parameter>
         <Parameter Name="Body" Value="{"app_id":"your_unique_app_identifier","webhook_url":"https://your-app.com/api/webhooks"}"></Parameter>
         <Parameter Name="ResponseFieldPath" Value="$.data.access_token, $.tokens[0].value"></Parameter>
         <Parameter Name="TargetVariable" Value="token,refresh"></Parameter>
     </Parameter>
   </Parameters>
   <Requests></Requests>
  </Scenario>

Here is a detailed explanation of the specific elements within the 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 setting.
Value The value of the authentication setting.
Father The name of parent parameters.
The authentication scenario includes three parent parameter types, each serving as a container to organize related child parameters into distinct setting groups.
  • CustomFieldList: Defines a set of fields for users to input authentication credentials (e.g., Client ID, Client Secret) in the configuration UI.
    Note: The variables captured in the custom fields are accessible for all the subsequent requests in the template.
  • PopulateTemplateString: Defines custom HTTP headers to be included in every predefined CRM / Helpdesk synchronization requests (e.g., user association, contact synchronization. etc.) sent to the CRM/Helpdesk system.
  • FollowUpList: Defines one or more automated API requests that are triggered after a specific event, such as after a token is successfully retrieved.
Parent parameter
Attribute Description
CustomFieldList (for Authentication credentials input)
Name The variable name of the custom field, which can be reference in the template.

For example, if you set the name to client_id, it can then be referenced as variable {{.client_id}}.
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, which will be displayed above the custom field in the configuration UI.
Value The pre-defined list of options.
Note:
  • This attribute is available when the Editor is set to list.
  • Use commas to separate multiple options. For example, option1,option2.
PopulateTemplateString (for Custom HTTP headers)
Type The type of the parameter, which should be fixed as Header.
Name The name of the custom header.
Value Header value, can be either a specific value or a variable.
Note: The variable name in the authentication field can be used. For example, if a variable named client_id is set, you can reference it in the header value as {{.client_id}}.
Description A brief explanation of the header’s function or purpose for reference.
FollowUpList (for follow-up requests)
Type The type of the parameter, which should be fixed as FollowUpRequest.
Name
  • For the parent parameter, the system will automatically generate an ID for it.
  • For the child parameters, this attribute can be used to fill in the name of the follow-up request settings.
Value The value of the follow-up request settings.
Authentication settings
Setting 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.
  • bearertoken: This method authenticates requests using a bearer token. Every HTTP request sent to the CRM/Helpdesk must include a header field in the format of Authorization: Bearer {{.AccessToken}}, where {{.AccessToken}} is the token value granted by 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 and bearertoken authentication method.
ContentType The content type of the token retrieval request.
Valid value:
  • application/json
  • application/x-www-form-urlencoded
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}}.
TokenRefreshEndpointMethod The HTTP request method for the token refresh API.
Valid value:
  • get
  • post
Note: This parameter is only available for oauth2 and bearertoken authentication method.
TokenRefreshEndpoint The API request URL for refreshing access token.
Note: This parameter is only available for oauth2 and bearertoken authentication method.
TokenRefreshContentType The content type of the token refresh request.
Valid value:
  • application/json
  • application/x-www-form-urlencoded
  • multipart/form-data
Note: This parameter is only available for oauth2 and bearertoken authentication method.
TokenRefreshInterval Define the time interval at which the token should be refreshed automatically (Unit: Minute).
Note: This parameter is only available for oauth2 and bearertoken authentication method.
TokenRefreshBody The request body for the token refresh API.
Note: This parameter is only available for oauth2 and bearertoken authentication method.
Follow-up request settings
Setting Description
TriggeredEvent The event that triggers this follow-up request.
Valid value:
  • token_retrieved: Initiate the follow-up request upon successful retrieval of an access token.
  • token_refreshed: Initiates the follow-up request upon successful refresh of an access token.
RequestMethod The HTTP method for the API request.
Valid value:
  • get
  • post
Url The endpoint URL for the subsequent operation.
For example, 
https://api.example.com/rest-services/login
Headers The HTTP headers of the request (in JSON format). You can use {{.varname}} to insert dynamic values.

For example,

{"Content-Type":"application/json", "X-Custom-Header": "{{.DynamicValue}}"}
Body The data payload of the request (in JSON format). You can use {{.varname}} to insert dynamic values.
For example,
{"lastName":"{{.LastName}}","ownerId":"{{.Id}}","phone":"{{.BusinessNumber}}"}
ResponseFieldPath The JSON path to extract data from the response of the follow-up request.
Note: Use commas , to separate multiple variable names. For example, $.data.access_token, $.tokens[0].value
TargetVariable Define the name of the system variable to store the value extracted from the response. These can be existing variables or new custom variables.
Note:
  • Use commas , to separate multiple variable names. For example, token,refresh.

  • The variables are assigned in the same order as the fields specified in the ResponseFieldPath. For example, the first variable receives the value from the first JSONPath, the second variable receives the value from the second JSONPath, and so on.

User association scenario

This scenarios is used to retrieve the list of users from the CRM/Helpdesk system. The structure of the scenario and its key elements are outlined as below:

<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>
            <Parameter Name="PaginationEnabled" Value="0" />
            <Parameter Name="PaginationType" Value="" />
            <Parameter Name="VarPageName" Value="page" />
            <Parameter Name="VarPageValue" Value="1" />
            <Parameter Name="VarPageSizeName" Value="page_size" />
            <Parameter Name="VarPageSizeValue" Value="10" />
            <Parameter Name="VarOffsetName" Value="from" />
            <Parameter Name="VarOffsetValue" Value="1" />
            <Parameter Name="VarLimitName" Value="limit" />
            <Parameter Name="VarLimitValue" Value="10" />
            <Parameter Name="VarNextPagePath" Value="links.next" />
     </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>

Here is a detailed explanation of the specific elements within the 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.
Parameter element
The <Parameter> element provides has the following attributes:
Attribute Description
Name The name of the pagination settings used in the scenario.
Value The value of the pagination settings.
Pagination settings
Setting Description
PaginationEnabled Whether to enable pagination.
Valid value:
  • 0: Disable.
  • 1: Enable.
PaginationType Specify the pagination mode.
Valid value:
  • page_based: Retrieve user data based on page number and page size.
  • offset_based: Retrieve user data based on a starting index and record limit.
  • link_based: Retrieve user data by using the URL pointing to the next page of data in the API response.
VarPageName Enter the parameter name used to specify the page number in API requests.
Note: This parameter is only available for page_based pagination mode.
VarPageValue Specify the initial page number from which to start querying data.
Note: This parameter is only available for page_based pagination mode.
VarPageSizeName Enter the parameter name used to specify the number of records per page in API requests.
Note: This parameter is only available for page_based pagination mode.
VarPageSizeValue Specify the maximum number of records to return in a single page.
Note: This parameter is only available for page_based pagination mode.
VarOffsetName Enter the parameter name used to specify the start position in API requests.
Note: This parameter is only available for offset_based pagination mode.
VarOffsetValue Specify the starting position for data retrieval by indicating the number of records to skip.

For example, a value of 1 starts from the first record, while 100 starts retrieval from the 100th record.

Note: This parameter is only available for offset_based pagination mode.
VarLimitName Enter the parameter name used to specify the number of records per page in API requests.
Note: This parameter is only available for offset_based pagination mode.
VarLimitValue Specify the maximum number of records to return in a single page.
Note: This parameter is only available for offset_based pagination mode.
VarNextPagePath Specify the JSON path (e.g. links.next) used to obtain the link pointing to the next page of data.
Note: This parameter is only available for link_based mode.
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.

Automatic contact synchronization scenario

This scenarios is used to search for contacts in the CRM/Helpdesk system, and the returned information can be used to implement CRM contacts searching, automatic contact synchronization and call popup. The structure of the scenario and its key elements are outlined as below: 

  <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>

Here is a detailed explanation of the specific elements within the 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.

Automatic contact creation scenario

This scenarios is used to create a new contact in the CRM/Helpdesk system when the caller’s number does not match any existing contact. The structure of the scenario and its key elements are outlined as below: 

 <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>

Here is a detailed explanation of the specific elements within the 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 &#xA; 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.

Automatic ticket creation scenario (for Helpdesk system only)

This scenarios is used to create a new ticket in the Helpdesk system. The structure of the scenario and its key elements are outlined as below: 

<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>

Here is a detailed explanation of the specific elements within the 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 &#xA; 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.
{{.LinkedId}} The unique ID of the call.
{{.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.

Call journal scenario

This scenarios is used to log the call activities of associated users to the CRM / Helpdesk. The structure of the scenario and its key elements are outlined as below: 

  <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>
    <Parameter Name="EnableForwardCallLogForAnsweredAgent" Value="0"></Parameter>
    <Parameter Name="ForwardCallLogForAnsweredAgent" 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>

Here is a detailed explanation of the specific elements within the 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 CallJournal.
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 the call log subject is configurable in the integration.
Valid value:
  • 0: Disable.
  • 1: Enable.
Subject Specify the default value of the subject.
Note: The default value is Extension Call, you can also specify the subject using the supported variables.
EnableDescription Whether to the call log description is configurable in the integration.
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.
EnablePlayCallRecording Whether the feature to play call recordings within the CRM/Helpdesk is configurable in the integration.
Valid value:
  • 0: Disable.
  • 1: Enable.
PlayCallRecording Specify the default status of the call recording playback option.
Valid value:
  • 0: Disable.
  • 1: Enable.
EnableForwardCallLogForAnsweredAgent Whether the option to prevent logging missed calls for queue or ring group calls to non-answering agents' CRM/Helpdesk is configurable in the integration.
ForwardCallLogForAnsweredAgent Specify the default status of the option to prevent logging missed calls for queue or ring group calls to non-answering agents' CRM/Helpdesk.
Valid value:
  • 0: Disable.
  • 1: Enable. Call logs for queue and ring group calls are synchronized only to the CRM/Helpdesk of the agent who answered the call, while missed call logs for the same call are not synchronized to the CRM of agents who did not answer.
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 CallJournal.
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 &#xA; 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 call.

This variable value is retrieved from the Subject parameter.
{{.Description}} The description of the call.

The variable value is retrieved from the Description parameter.
{{.LinkedId}} The unique ID of the call.
{{.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.
{{.EnableCallRecording}} Whether the call recording is enabled.
Possible value:
  • 0: Disabled.
  • 1: Enabled.

Extended configurations

In addition to the scenarios specified in the configuration page, you can also manually add custom configurations for supplementary use.
Note: Custom configurations in the template are preserved and will not be affected by changes made through the PBX web portal.
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.