CCH KPI Monitoring : REST API Triggers

Web API Designer Definition Tab

On the Web API Designer Definition tab, fill in the following values:

• Description:  The title for your entry, such as “New York Times”.
• Active:  Check this box if you want this trigger to run.
• Notes:  Any additional notes you want.
• URI:  The base web address for the API, such as “https://api.nytimes.com/”.  

• Resource:  The sub-path for the API call, such as “svc/movies/v2/reviews/search.json”. 

  KPI Monitoring will replace {bracketed} variables in this field if the variables were defined in a previously-executed trigger, or if it’s a standard variable, such as a date variable. 
  
  The URI and Resource fields are appended to each other without a delimiter to create the full URI path.  In the examples above, the full URI will become “https://api.nytimes.com/svc/movies/v...ws/search.json”.
   

•    Verb:  This is the REST API call verb to use.  GET is the default and will be appropriate in most cases.
•    Format: Select JSON or XML. The parsed XML response and the structure of the XML data are displayed on the Response tab.
•    Ignore Response Code: Check this box to ignore incoming HTTP response codes from the Web API. 

• API Uses JSON Template: Check this box if the data parameters in the Web API are defined in a JSON template. KPI Monitoring generates a complex JSON object using the template. (Currently, this is only available for Web API triggers.) See next section for more details. 

Web API Calls with Advanced JSON

By default, the API Uses JSON Template box is not checked if the following is true: 

• For new/existing Web API definitions 
• For copied/pasted Web API definitions 
• If an eventpak does not contain a value for this flag 
• If format is in XML 

If the Web API trigger has API Uses JSON Template checked: 

• JSON is created for every parameter that has a template, using response data from previous query or Web 
• API triggers. 
• After the Web API is triggered, all response data from previous triggers is cleared. 
• A new response data set is created with the results from the Web API. 

The following examples use this data table: 

Advanced JSON Example 1

If the JSON template has a top-level collection (e.g., square brackets [] surround the entire JSON code), a single call is made to the Web API and the JSON collection is passed as a parameter: 

Advanced JSON Example 2

If the JSON template does not have a top-level collection, there will be multiple calls to the Web API based on the results in the data table. There is one call per top-level entity. In the example below, the top-level entity is Customer. There will be two calls to the Web API, one for CUSTA and then one for CUSTB: 

Web API Designer Authorization tab

On the Authorization tab, pick the authorization type.  If you are using an API key, do not use the Authorization Type setting and instead pass it using a key-value pair in the Parameters tab.

• No Auth:  Do not pass authorization credentials.
• Basic Auth:  Enter the username and password you created for the API.
• OAuth 2.0: Please see the section below.

OAuth 2.0

• OAuth 2.0 is the industry-standard protocol for authorization which allows third-party applications to grant limited access to an HTTP service, either on behalf of a resource owner or by allowing the third-party application to obtain access on its own behalf.
• OAuth2 requires the use of HTTPS for communication between the client and the authorization server because of sensitive data passing between the two. 

When selecting OAuth 2.0 as an authorization type, additional information is needed for authentication:

• Access Token:  Click the Request Token button at the bottom of the screen and a token is sent from the third-party application and it is automatically populated. Access Token is masked. The token is saved by selecting the Use Saved Access Token for All Requests check box and used for all requests to this API during event execution. If unchecked, a new Access Token will be generated for each new request.
• Grant Type: The method of acquiring an access token. Choose one of the following types:
  o    Authorization Code: Use when the client is a web server. Allows you to obtain a long-term access token since it can be renewed with a refresh token if the authorization sever enables it. The following information is required for this grant:

- Callback URL (This is generated by KPI Monitoring.)
- Auth URL
- Access Token URL
- Client ID (masked)
- Client Secret (masked)
- Scope
- State

o    Authorization Code (with PKCE): Proof Key for Code Exchange, use to authenticate native or mobile application users. Because a client_secret isn’t required, this reduces security risks. The following information is required for this grant:

- Callback URL
- Auth URL
- Access Token URL
- Code Challenge Method
- Code Verifier
- Client ID (masked)
- Client Secret (masked)
- Scope
- State

o    Implicit: Use when the client is running in a browser and using a scripting language, e.g., JavaScript. This grant type does not allow for the issuance of a refresh token. The following information is required for this grant:

- Callback URL
- Auth URL
- Access Token URL
- Client ID (masked)
- Client Secret (masked)
- Scope
- State

o    Password Credentials: Use when the client has been developed by the same authority as the authorization server. With this type of authorization, the credentials (and thus the password) are sent to the client and then to the authorization server. The following information is required for this grant:

- Access Token URL
- Username
- Password
- Client ID (masked)
- Client Secret (masked)
- Scope

o    Client Credentials: Use when the client is himself the resource owner. There is no authorization to obtain from the end-user. The following information is required for this grant:

- Access Token URL
- Client ID (masked)
- Client Secret (masked)
- Scope

Client Authentication: Chose one of the following types for sending client authentication:

o    Send as Basic Auth header
o    Send client credentials in body
o    Send Query String

Check the box for Use Saved Access Token for All Requests when creating a new connection with credentials that will be used for several events and eventpaks. When creating an event, users can select from a list of established connections to auto-populate the credential information.

Web API Designer Parameters tab

On the Parameters tab:

• Variables:  Search for a system variable here, and then double-click it to insert the variable into the Value field.
• Parameter Type:  Choose what works best for you:
  • Get or Post:  This behaves differently based on the verb.  In both cases, name and value are URL-encoded.
    • Get:  Parameters are appended to the URL in the form URL?name1=value1&name2=value2. 
    • Post or Put:  Parameters are sent in the request body.
  • Query String:  This works like “Get or Post”, except it appends the parameters to the URL in the form URL?name1=value1&name2=value2 regardless of the selected verb.
  • URL Segment:  When the request executes, this parameter type replaces a {bracketed} variable in the URI field having {Name} with the Value.
  • Http Header:  Adds the parameter as an HTTP header sent along with the request.  The header name is the name of the parameter and the header value is the value.
  • Request Body:  If this parameter is set, its value is sent as the body of the request. Only the first Request Body parameter is accepted.  

    Request Body does not work on Get requests, as they do not actually send a body.  If you have “Get or Post” parameters as well, they will replace the Request Body parameter.

  • Cookie:  Adds the parameter to the list of cookies sent along with the request.
  • Request Root: If this parameter is set, its value is sent as the root of the request.
• Key:  The key portion of the key-value pair.
• Value:  The value portion of the key-value pair.  

You can also insert system variables in {brackets} that were defined in previously executed web API triggers. This example shows how you can include a “summary_shorts” variable as a value.  Your custom variables will not display in the Variables list, but you can manually type them.

• Event Parameter:  Specifies where the web API definition will get the value for this parameter:
  • Checked:  KPI Monitoring will get the value from the event that uses this Web API as a trigger.  To set the value, go to the Trigger properties section in the event’s screen. If the event does not provide a value, KPI Monitoring will use the value entered in this web API definition as the default.
  • Unchecked:  KPI Monitoring will get the value from the Value field within the Web API definition.
• Combine All parameters into a JSON (XML) Request Body:  Check this option if your web API requires all parameters to be combined into a single JSON or XML object in the body of the request rather than sent as individual parameters. (The parameter shown defaults to the Format selected on the Definition tab.)

Filtering API Example:  Filtering New York Times Movie Reviews

The New York Times Movie API allows you to pass filter using several methods.  This permits you to have the API perform the filtering.  No further filtering is required once the data is in KPI Monitoring.

Movie Title

The “query” parameter accepts the value of the movie title, as shown below:

 
You could substitute a KPI Monitoring variable in the place of “godfather”.

Movie Title and Opening Date

Additional filtering can be performed on many different fields on this API.  This example finds movies with “big” in the title opening during the 1980s.

Non-Filtering API Example:  Filtering on Date for Lasso CRM

In this example, we’ll get a list of properties from Lasso CRM.  We want to email property owners three days before their property possession date.  In this case the REST API does not support filtering, so to do this we’ll get a list of properties from the API, use the database engine to filter the list, and then send an email.
Getting Keys in Three Days
 - Create REST API Trigger
Create a new Web API object.  From the example below, you see the API response includes dates.

 
Create Database Connection
Create a database connection to use in the next step.  We connected to KS_Object, but the actual database doesn’t matter since we’ll only use the query engine for our date comparison, and we won’t read or modify any data tables.

 
Create Query
Create a query using any database table.  In the example below, we used the “admin” table.

• Use the database connection from the previous step.
• Add a calculated column with value = 1.  This column isn’t used, but KPI Monitoring requires at least one field in a query.
• Set Return Distinct Rows of Data Only = Checked.
  
   
• Go to the Filters tab and create a SQL filter statement.  This statement is:

DATEADD(DAY,-3,'{%Current Date%}')

This statement is SQL language intended for SQL Server.  It subtracts three days from the current date. It will be used in the event in next step to compare with the property possession date.
There are several settings in addition to the SQL statement, such as Type = Date.

 
Create Event

• Add two triggers, which must appear in this order
  1.    Inventory List (Gets the list of properties)
  2.    Is Current Date? (Compare each item in the Inventory List using their possession date with the date that is “three days from now”)
  
• For the second trigger, set the Parameter Value to “{Possession Date}”.  

  Note: Variables from the REST API trigger will not appear in the “Available Values for Use:” box, but if you type the value, it will be accepted and will work.

Create Email
Create a standard KPI Monitoring email action.  We used a BEGIN/END REPEAT to group properties.

Contract Date within 7 Days of Possession Date

Create REST API Trigger
Create a new Web API object like the same step in the previous example.
For reference, we will compare the two values from the response shown:

 
Create Database Connection
Create a database connection like the same step in the previous example.
Create Query
Create a query using any database table.  In the example below, we used the “admin” table.

• Use the database connection from the previous step.
• Add a calculated column with value = 1.  This column isn’t used, but KPI Monitoring requires at least one field in a query.
• Set Return Distinct Rows of Data Only = Checked.
• See §3.1.3 for a sample screen shot for the progress to this point.
• Go to the Filters tab and create a SQL filter statement.  This statement is:

7

This statement is a single numeric value that will be later combined with SQL language intended for SQL Server.

  
Create Event  
Add two triggers, which must appear in this order:

1. Inventory List (Gets the list of properties)
2. Date 1 Within 7 Days of Date 2? (Compare each item in the Inventory List using their possession and contract dates with the value 7 in “Date 1 Within 7 Days of Date 2”)

Create Email
Create a standard KPI Monitoring email action like the same step in the previous example.

• For the second trigger, set the Parameter Value to “DATEDIFF(day, '{Possession Date}', '{Contract Date}')”.